Standard::getName() - Code Metrics - aimeos/ai-controller-jobs - Measure and Improve Code Quality continuously with Scrutinizer

Standard::getName() A
last analyzed 2025-12-03 12:48 UTC

↳ Parent: Standard
Complexity

Conditions	1
Paths	1
Size

Total Lines	3
Code Lines	1
Duplication

Lines	0
Ratio	0 %
Importance

Changes	1
Bugs	0	Features	0
Metric	Value
cc	1
eloc	1
c	1
b	0
f	0
nc	1
nop	0
dl	0
loc	3
rs	10
<?php

/**
 * @license LGPLv3, http://opensource.org/licenses/LGPL-3.0
 * @copyright Aimeos (aimeos.org), 2025
 * @package Controller
 * @subpackage Jobs
 */


namespace Aimeos\Controller\Jobs\Customer\Import\Csv;


/**
 * Job controller for CSV customer imports.
 *
 * @package Controller
 * @subpackage Jobs
 */
class Standard
	extends \Aimeos\Controller\Jobs\Common\Customer\Import\Csv\Base
	implements \Aimeos\Controller\Jobs\Iface
{
	/** controller/jobs/customer/import/csv/name
	 * Class name of the used customer suggestions scheduler controller implementation
	 *
	 * Each default job controller can be replace by an alternative imlementation.
	 * To use this implementation, you have to set the last part of the class
	 * name as configuration value so the controller factory knows which class it
	 * has to instantiate.
	 *
	 * For example, if the name of the default class is
	 *
	 *  \Aimeos\Controller\Jobs\Customer\Import\Csv\Standard
	 *
	 * and you want to replace it with your own version named
	 *
	 *  \Aimeos\Controller\Jobs\Customer\Import\Csv\Mycsv
	 *
	 * then you have to set the this configuration option:
	 *
	 *  controller/jobs/customer/import/csv/name = Mycsv
	 *
	 * The value is the last part of your own class name and it's case sensitive,
	 * so take care that the configuration value is exactly named like the last
	 * part of the class name.
	 *
	 * The allowed characters of the class name are A-Z, a-z and 0-9. No other
	 * characters are possible! You should always start the last part of the class
	 * name with an upper case character and continue only with lower case characters
	 * or numbers. Avoid chamel case names like "MyCsv"!
	 *
	 * @param string Last part of the class name
	 * @since 2025.10
	 */

	/** controller/jobs/customer/import/csv/decorators/excludes
	 * Excludes decorators added by the "common" option from the customer import CSV job controller
	 *
	 * Decorators extend the functionality of a class by adding new aspects
	 * (e.g. log what is currently done), executing the methods of the underlying
	 * class only in certain conditions (e.g. only for logged in users) or
	 * modify what is returned to the caller.
	 *
	 * This option allows you to remove a decorator added via
	 * "controller/jobs/common/decorators/default" before they are wrapped
	 * around the job controller.
	 *
	 *  controller/jobs/customer/import/csv/decorators/excludes = array( 'decorator1' )
	 *
	 * This would remove the decorator named "decorator1" from the list of
	 * common decorators ("\Aimeos\Controller\Jobs\Common\Decorator\*") added via
	 * "controller/jobs/common/decorators/default" to the job controller.
	 *
	 * @param array List of decorator names
	 * @since 2025.10
	 * @see controller/jobs/common/decorators/default
	 * @see controller/jobs/customer/import/csv/decorators/global
	 * @see controller/jobs/customer/import/csv/decorators/local
	 */

	/** controller/jobs/customer/import/csv/decorators/global
	 * Adds a list of globally available decorators only to the customer import CSV job controller
	 *
	 * Decorators extend the functionality of a class by adding new aspects
	 * (e.g. log what is currently done), executing the methods of the underlying
	 * class only in certain conditions (e.g. only for logged in users) or
	 * modify what is returned to the caller.
	 *
	 * This option allows you to wrap global decorators
	 * ("\Aimeos\Controller\Jobs\Common\Decorator\*") around the job controller.
	 *
	 *  controller/jobs/customer/import/csv/decorators/global = array( 'decorator1' )
	 *
	 * This would add the decorator named "decorator1" defined by
	 * "\Aimeos\Controller\Jobs\Common\Decorator\Decorator1" only to the job controller.
	 *
	 * @param array List of decorator names
	 * @since 2025.10
	 * @see controller/jobs/common/decorators/default
	 * @see controller/jobs/customer/import/csv/decorators/excludes
	 * @see controller/jobs/customer/import/csv/decorators/local
	 */

	/** controller/jobs/customer/import/csv/decorators/local
	 * Adds a list of local decorators only to the customer import CSV job controller
	 *
	 * Decorators extend the functionality of a class by adding new aspects
	 * (e.g. log what is currently done), executing the methods of the underlying
	 * class only in certain conditions (e.g. only for logged in users) or
	 * modify what is returned to the caller.
	 *
	 * This option allows you to wrap local decorators
	 * ("\Aimeos\Controller\Jobs\Customer\Import\Csv\Decorator\*") around the job
	 * controller.
	 *
	 *  controller/jobs/customer/import/csv/decorators/local = array( 'decorator2' )
	 *
	 * This would add the decorator named "decorator2" defined by
	 * "\Aimeos\Controller\Jobs\Customer\Import\Csv\Decorator\Decorator2"
	 * only to the job controller.
	 *
	 * @param array List of decorator names
	 * @since 2025.10
	 * @see controller/jobs/common/decorators/default
	 * @see controller/jobs/customer/import/csv/decorators/excludes
	 * @see controller/jobs/customer/import/csv/decorators/global
	 */


	/**
	 * Returns the localized name of the job.
	 *
	 * @return string Name of the job
	 */
	public function getName() : string
	{
		return $this->context()->translate( 'controller/jobs', 'Customer import CSV' );
	}


	/**
	 * Returns the localized description of the job.
	 *
	 * @return string Description of the job
	 */
	public function getDescription() : string
	{
		return $this->context()->translate( 'controller/jobs', 'Imports new and updates existing customers from CSV files' );
	}


	/**
	 * Executes the job.
	 *
	 * @throws \Aimeos\Controller\Jobs\Exception If an error occurs
	 */
	public function run()
	{
		$context = $this->context();
		$logger = $context->logger();
		$date = date( 'Y-m-d H:i:s' );

		try
		{
			$files = $errors = 0;
			$fs = $context->fs( 'fs-import' );
			$site = $context->locale()->getSiteItem()->getCode();
			$location = $this->location() . '/' . $site;

			if( $fs->isDir( $location ) === false ) {
				return;
			}

			$logger->info( sprintf( 'Started customer import from "%1$s"', $location ), 'import/csv/customer' );

			foreach( map( $fs->scan( $location ) )->sort() as $filename )
			{
				$path = $location . '/' . $filename;

				if( $filename[0] === '.' || $fs instanceof \Aimeos\Base\Filesystem\DirIface && $fs->isDir( $path ) ) {
					continue;
				}

				$errors = $this->import( $path );
				$files++;
			}

			/** controller/jobs/customer/import/csv/cleanup
			 * Deletes all customers with categories which havn't been updated
			 *
			 * By default, the customer importer only adds new and updates existing
			 * customers but doesn't delete any customers. If you want to remove all
			 * customers which haven't been updated during the import, then set this
			 * configuration option to "true". This will remove all customers which
			 * are not assigned to any category but keep the ones without categories,
			 * e.g. rebate customers.
			 *
			 * @param bool TRUE to delete all untouched customers, FALSE to keep them
			 * @since 2025.10
			 * @see controller/jobs/customer/import/csv/backup
			 * @see controller/jobs/customer/import/csv/domains
			 * @see controller/jobs/customer/import/csv/location
			 * @see controller/jobs/customer/import/csv/mapping
			 * @see controller/jobs/customer/import/csv/max-size
			 * @see controller/jobs/customer/import/csv/skip-lines
			 */
			if( $files && $context->config()->get( 'controller/jobs/customer/import/csv/cleanup', false ) )
			{
				$count = $this->cleanup( $date );
				$logger->info( sprintf( 'Cleaned %1$s old customers', $count ), 'import/csv/customer' );
			}

			if( $errors > 0 ) {
				$this->mail( 'Customer CSV import', sprintf( 'Invalid customer lines during import: %1$d', $errors ) );
			}

			$logger->info( sprintf( 'Finished customer import from "%1$s"', $location ), 'import/csv/customer' );
		}
		catch( \Exception $e )
		{
			$logger->error( 'Customer import error: ' . $e->getMessage() . "\n" . $e->getTraceAsString(), 'import/csv/customer' );
			$this->mail( 'Customer CSV import error', $e->getMessage() . "\n" . $e->getTraceAsString() );
			throw new \Aimeos\Controller\Jobs\Exception( $e->getMessage() );
		}
	}


	/**
	 * Returns the directory for storing imported files
	 *
	 * @return string Directory for storing imported files
	 */
	protected function backup() : string
	{
		/** controller/jobs/customer/import/csv/backup
		 * Name of the backup for sucessfully imported files
		 *
		 * After a CSV file was imported successfully, you can move it to another
		 * location, so it won't be imported again and isn't overwritten by the
		 * next file that is stored at the same location in the file system.
		 *
		 * You should use an absolute path to be sure but can be relative path
		 * if you absolutely know from where the job will be executed from. The
		 * name of the new backup location can contain placeholders understood
		 * by the PHP DateTime::format() method (with percent signs prefix) to
		 * create dynamic paths, e.g. "backup/%Y-%m-%d" which would create
		 * "backup/2000-01-01". For more information about the date() placeholders,
		 * please have a look  into the PHP documentation of the
		 * {@link https://www.php.net/manual/en/datetime.format.php format() method}.
		 *
		 * **Note:** If no backup name is configured, the file will be removed!
		 *
		 * @param integer Name of the backup file, optionally with date/time placeholders
		 * @since 2025.10
		 * @see controller/jobs/customer/import/csv/cleanup
		 * @see controller/jobs/customer/import/csv/domains
		 * @see controller/jobs/customer/import/csv/location
		 * @see controller/jobs/customer/import/csv/mapping
		 * @see controller/jobs/customer/import/csv/max-size
		 * @see controller/jobs/customer/import/csv/skip-lines
		 */
		$backup = $this->context()->config()->get( 'controller/jobs/customer/import/csv/backup' );
		return \Aimeos\Base\Str::strtime( (string) $backup );
	}


	/**
	 * Cleans up the given list of customer items
	 *
	 * @param \Aimeos\Map $customers List of customer items implementing \Aimeos\MShop\Customer\Item\Iface
	 */
	protected function clean( \Aimeos\Map $customers )
	{
		$manager = \Aimeos\MShop::create( $this->context(), 'customer' );

		$manager->begin();
		$manager->save( $customers->setStatus( -2 ) );
		$manager->commit();
	}


	/**
	 * Adds conditions to the filter for fetching customers that should be removed
	 *
	 * @param \Aimeos\Base\Criteria\Iface $filter Criteria object
	 * @return \Aimeos\Base\Criteria\Iface Modified criteria object
	 */
	protected function cleaner( \Aimeos\Base\Criteria\Iface $filter ) : \Aimeos\Base\Criteria\Iface
	{
		return $filter;
	}


	/**
	 * Removes all customers which have been updated before the given date/time
	 *
	 * @param string $datetime Date and time in ISO format
	 * @return int Number of removed customers
	 */
	protected function cleanup( string $datetime ) : int
	{
		$count = 0;
		$manager = \Aimeos\MShop::create( $this->context(), 'customer' );

		$filter = $manager->filter();
		$filter->add( 'customer.mtime', '<', $datetime );
		$cursor = $manager->cursor( $this->call( 'cleaner', $filter ) );

		while( $items = $manager->iterate( $cursor, ['customer' => ['default']] ) )
		{
			$this->call( 'clean', $items );
			$count += count( $items );
		}

		return $count;
	}


	/**
	 * Returns the list of domain names that should be retrieved along with the attribute items
	 *
	 * @return array List of domain names
	 */
	protected function domains() : array
	{
		$default = ['customer/address', 'customer/property'];

		/** controller/jobs/customer/import/csv/domains
		 * List of item domain names that should be retrieved along with the customer items
		 *
		 * For efficient processing, the items associated to the customers can be
		 * fetched to, minimizing the number of database queries required. To be
		 * most effective, the list of item domain names should be used in the
		 * mapping configuration too, so the retrieved items will be used during
		 * the import.
		 *
		 * @param array Associative list of MShop item domain names
		 * @since 2025.10
		 * @see controller/jobs/customer/import/csv/backup
		 * @see controller/jobs/customer/import/csv/cleanup
		 * @see controller/jobs/customer/import/csv/location
		 * @see controller/jobs/customer/import/csv/mapping
		 * @see controller/jobs/customer/import/csv/max-size
		 * @see controller/jobs/customer/import/csv/skip-lines
		 */
		return $this->context()->config()->get( 'controller/jobs/customer/import/csv/domains', $default );
	}


	/**
	 * Returns the position of the "customer.code" column from the customer item mapping
	 *
	 * @param array $mapping Mapping of the "item" columns with position as key and code as value
	 * @return int Position of the "customer.code" column
	 * @throws \Aimeos\Controller\Jobs\Exception If no mapping for "customer.code" is found
	 */
	protected function getCodePosition( array $mapping ) : int
	{
		foreach( $mapping as $pos => $key )
		{
			if( $key === 'customer.code' ) {
				return $pos;
			}
		}

		throw new \Aimeos\Controller\Jobs\Exception( sprintf( 'No "customer.code" column in CSV mapping found' ) );
	}


	/**
	 * Returns the customer items for the given codes
	 *
	 * @param array $codes List of customer codes
	 * @param array $domains List of domains whose items should be fetched too
	 * @return \Aimeos\Map Associative list of customer codes as key and customer items as value
	 */
	protected function getCustomers( array $codes, array $domains ) : \Aimeos\Map
	{
		$manager = \Aimeos\MShop::create( $this->context(), 'customer' );
		$search = $manager->filter()->add( ['customer.code' => $codes] )->slice( 0, count( $codes ) );

		return $manager->search( $search, $domains )->col( null, 'customer.code' );
	}


	/**
	 * Imports the CSV file from the given path
	 *
	 * @param string $path Relative path to the CSV file
	 * @return int Number of lines which couldn't be imported
	 */
	protected function import( string $path ) : int
	{
		$context = $this->context();
		$logger = $context->logger();

		$logger->info( sprintf( 'Started customer import from "%1$s"', $path ), 'import/csv/customer' );

		$maxcnt = $this->max();
		$skiplines = $this->skip();
		$domains = $this->domains();

		$mappings = $this->mapping();
		$processor = $this->getProcessors( $mappings );
		$codePos = $this->getCodePosition( $mappings['item'] );

		$fs = $context->fs( 'fs-import' );
		$fh = $fs->reads( $path );
		$total = $errors = 0;

		for( $i = 0; $i < $skiplines; $i++ ) {
			fgetcsv( $fh, null, ',', '"', '' );
		}

		while( ( $data = $this->getData( $fh, $maxcnt, $codePos ) ) !== [] )
		{
			$customers = $this->getCustomers( array_keys( $data ), $domains );
			$errors += $this->importCustomers( $customers, $data, $mappings['item'], [], $processor );

			$total += count( $data );
			unset( $customers, $data );
		}

		$processor->finish();
		fclose( $fh );

		if( !empty( $backup = $this->backup() ) ) {
			$fs->move( $path, $backup );
		} else {
			$fs->rm( $path );
		}

		$str = sprintf( 'Finished customer import from "%1$s" (%2$d/%3$d)', $path, $errors, $total );
		$logger->info( $str, 'import/csv/customer' );

		return $errors;
	}


	/**
	 * Imports the CSV data and creates new customers or updates existing ones
	 *
	 * @param \Aimeos\Map $customers List of customers items implementing \Aimeos\MShop\Customer\Item\Iface
	 * @param array $data Associative list of import data as index/value pairs
	 * @param array $mapping Associative list of positions and domain item keys
	 * @param array $types List of allowed customer type codes
	 * @param \Aimeos\Controller\Jobs\Common\Customer\Import\Csv\Processor\Iface $processor Processor object
	 * @return int Number of customers that couldn't be imported
	 * @throws \Aimeos\Controller\Jobs\Exception
	 */
	protected function importCustomers( \Aimeos\Map $customers, array $data, array $mapping, array $types,
		\Aimeos\Controller\Jobs\Common\Customer\Import\Csv\Processor\Iface $processor ) : int
	{
		$items = [];
		$errors = 0;
		$context = $this->context();
		$manager = \Aimeos\MShop::create( $context, 'customer' );

		foreach( $data as $code => $list )
		{
			$manager->begin();

			try
			{
				$code = trim( $code );
				$customer = $customers[$code] ?? $manager->create();
				$map = current( $this->getMappedChunk( $list, $mapping ) ); // there can only be one chunk for the base customer data

				if( $map )
				{
					$this->check( $map );
					$customer = $manager->save( $customer->fromArray( $map, true ) );

					$processor->process( $customer, $list );
					$processor->process( /** @scrutinizer ignore-type */ $customer, $list );

					$customer = $manager->save( $customer );
					$items[$customer->getId()] = $customer;
				}

				$manager->commit();
			}
			catch( \Throwable $t )
			{
				$manager->rollback();

				$msg = sprintf( 'Unable to import customer with code "%1$s": %2$s', $code, $t->getMessage() );
				$context->logger()->error( $msg, 'import/csv/customer' );

				$errors++;
			}
		}

		return $errors;
	}


	/**
	 * Returns the path to the directory with the CSV file
	 *
	 * @return string Path to the directory with the CSV file
	 */
	protected function location() : string
	{
		/** controller/jobs/customer/import/csv/location
		 * Directory where the CSV files are stored which should be imported
		 *
		 * It's the relative path inside the "fs-import" virtual file system
		 * configuration. The default location of the "fs-import" file system is:
		 *
		 * * Laravel: ./storage/import/
		 * * TYPO3: /uploads/tx_aimeos/.secure/import/
		 *
		 * @param string Relative path to the CSV files
		 * @since 2015.08
		 * @see controller/jobs/customer/import/csv/backup
		 * @see controller/jobs/customer/import/csv/cleanup
		 * @see controller/jobs/customer/import/csv/domains
		 * @see controller/jobs/customer/import/csv/location
		 * @see controller/jobs/customer/import/csv/mapping
		 * @see controller/jobs/customer/import/csv/max-size
		 * @see controller/jobs/customer/import/csv/skip-lines
		 */
		return (string) $this->context()->config()->get( 'controller/jobs/customer/import/csv/location', 'customer' );
	}


	/**
	 * Returns the CSV column mapping
	 *
	 * @return array CSV column mapping
	 */
	protected function mapping() : array
	{
		/** controller/jobs/customer/import/csv/mapping
		 * List of mappings between the position in the CSV file and item keys
		 *
		 * The importer have to know which data is at which position in the CSV
		 * file. Therefore, you need to specify a mapping between each position
		 * and the MShop domain item key (e.g. "customer.code") it represents.
		 *
		 * You can use all domain item keys which are used in the fromArray()
		 * methods of the item classes.
		 *
		 * These mappings are grouped together by their processor names, which
		 * are responsible for importing the data, e.g. all mappings in "item"
		 * will be processed by the base customer importer while the mappings in
		 * "text" will be imported by the text processor.
		 *
		 * @param array Associative list of processor names and lists of key/position pairs
		 * @since 2025.10
		 * @see controller/jobs/customer/import/csv/backup
		 * @see controller/jobs/customer/import/csv/cleanup
		 * @see controller/jobs/customer/import/csv/domains
		 * @see controller/jobs/customer/import/csv/location
		 * @see controller/jobs/customer/import/csv/max-size
		 * @see controller/jobs/customer/import/csv/skip-lines
		 */
		$map = (array) $this->context()->config()->get( 'controller/jobs/customer/import/csv/mapping', $this->getDefaultMapping() );

		if( !isset( $map['item'] ) || !is_array( $map['item'] ) )
		{
			$msg = sprintf( 'Required mapping key "%1$s" is missing or contains no array', 'item' );
			throw new \Aimeos\Controller\Jobs\Exception( $msg );
		}

		return $map;
	}


	/**
	 * Returns the maximum number of CSV rows to import at once
	 *
	 * @return int Maximum number of CSV rows to import at once
	 */
	protected function max() : int
	{
		/** controller/jobs/customer/import/csv/max-size
		 * Maximum number of CSV rows to import at once
		 *
		 * It's more efficient to read and import more than one row at a time
		 * to speed up the import. Usually, the bigger the chunk that is imported
		 * at once, the less time the importer will need. The downside is that
		 * the amount of memory required by the import process will increase as
		 * well. Therefore, it's a trade-off between memory consumption and
		 * import speed.
		 *
		 * @param integer Number of rows
		 * @since 2025.10
		 * @see controller/jobs/customer/import/csv/backup
		 * @see controller/jobs/customer/import/csv/cleanup
		 * @see controller/jobs/customer/import/csv/domains
		 * @see controller/jobs/customer/import/csv/location
		 * @see controller/jobs/customer/import/csv/mapping
		 * @see controller/jobs/customer/import/csv/skip-lines
		 */
		return (int) $this->context()->config()->get( 'controller/jobs/customer/import/csv/max-size', 1000 );
	}


	/**
	 * Returns the number of rows skipped in front of each CSV files
	 *
	 * @return int Number of rows skipped in front of each CSV files
	 */
	protected function skip() : int
	{
		/** controller/jobs/customer/import/csv/skip-lines
		 * Number of rows skipped in front of each CSV files
		 *
		 * Some CSV files contain header information describing the content of
		 * the column values. These data is for informational purpose only and
		 * can't be imported into the database. Using this option, you can
		 * define the number of lines that should be left out before the import
		 * begins.
		 *
		 * @param integer Number of rows
		 * @since 2015.08
		 * @see controller/jobs/customer/import/csv/backup
		 * @see controller/jobs/customer/import/csv/cleanup
		 * @see controller/jobs/customer/import/csv/domains
		 * @see controller/jobs/customer/import/csv/location
		 * @see controller/jobs/customer/import/csv/mapping
		 * @see controller/jobs/customer/import/csv/max-size
		 */
		return (int) $this->context()->config()->get( 'controller/jobs/customer/import/csv/skip-lines', 0 );
	}
}

aimeos / ai-controller-jobs

Standard::getName() A last analyzed 2025-12-03 12:48 UTC

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like

Standard::getName() A
last analyzed 2025-12-03 12:48 UTC
