Annotated Code & Style Reference

/**
 * Create or update a customer.
 *
 * EXECUTION FLOW:
 * 1. TransactionWrapper::beforeSave() - Opens database transaction
 * 2. Validation (email format, required fields, uniqueness)
 * 3. Convert DTO to Model (CustomerInterface → Customer)
 * 4. Set password_hash if provided
 * 5. Database persistence (INSERT/UPDATE customer_entity + EAV)
 * 6. Save addresses if included
 * 7. EVENT: customer_save_after_data_object
 *    - Triggers email sync observers
 * 8. TransactionWrapper::afterSave() - Commits transaction
 * 9. Return saved CustomerInterface DTO
 *
 * TRANSACTION SAFETY:
 * The TransactionWrapper plugin ensures:
 * - Customer + addresses saved atomically
 * - Email sync observers run in same transaction
 * - Validation failures rollback everything
 *
 * PASSWORD HANDLING:
 * CREATE with password:
 *   $hash = $encryptor->getHash($plainPassword, true);
 *   $repository->save($customer, $hash);
 *
 * UPDATE without changing password:
 *   $repository->save($customer); // Don't pass hash
 *
 * @param CustomerInterface $customer Customer data object
 * @param string|null $passwordHash Hashed password (optional)
 * @return CustomerInterface Saved customer with generated ID
 */
public function save(
    \Magento\Customer\Api\Data\CustomerInterface $customer,
    $passwordHash = null
);

/**
 * Get customer by Customer ID.
 *
 * PREFERRED LOOKUP METHOD - Uses primary key (entity_id)
 *
 * Database query: SELECT * FROM customer_entity WHERE entity_id = ?
 * Performance: O(1) - direct primary key lookup
 *
 * This method loads:
 * - customer_entity row (main table)
 * - All EAV attributes (joins to customer_entity_varchar, _int, etc.)
 * - Custom attributes (if defined)
 * - Extension attributes (if defined)
 *
 * Does NOT load:
 * - Addresses (must call AddressRepositoryInterface separately)
 *
 * WHERE TO GET CUSTOMER ID:
 * - Customer session: $this->session->getCustomerId()
 * - Order: $order->getCustomerId()
 * - Quote: $quote->getCustomerId()
 * - URL parameter: $this->getRequest()->getParam('customer_id')
 *
 * @param int $customerId Customer ID (entity_id)
 * @return CustomerInterface Customer data object
 * @throws NoSuchEntityException If customer doesn't exist
 */
public function getById($customerId);

/**
 * Retrieve customers which match specified criteria.
 *
 * Example usage:
 */
$searchCriteria = $this->searchCriteriaBuilder
    ->addFilter('email', '%@example.com', 'like')
    ->addFilter('group_id', [1, 2], 'in')
    ->addFilter('website_id', $websiteId)
    ->setPageSize(50)
    ->setCurrentPage(1)
    ->addSortOrder(
        $this->sortOrderBuilder
            ->setField('created_at')
            ->setDirection('DESC')
            ->create()
    )
    ->create();

$results = $this->customerRepository->getList($searchCriteria);

echo "Total customers: " . $results->getTotalCount();
foreach ($results->getItems() as $customer) {
    echo $customer->getEmail() . "\n";
}