Symfony 1C Import Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider, facade, config file in config/, or Eloquent integration. Treat it accordingly before you composer require anything.

1. Confirm your intent. Two viable paths:
   • Sidecar service (recommended): run faustddd/symfony-1c-import in a small Symfony 6.4/7.x/8.x app that exposes the 1C exchange endpoint(s), then hand data to your Laravel app over HTTP, a shared database, or a queue message. Your Laravel app stays the source of truth for products, prices, and stock.
   • Extract-and-wire: pull the importer/parser classes into Laravel and register them yourself in a service provider. Only do this if the classes you need are not container/Kernel-coupled; the bundle's exchange and session handling generally is, so this path usually fights the framework.
2. Check the platform. PHP 8.2+, and ext-xmlreader, ext-simplexml, ext-zip must be installed in the runtime that parses files. In Laravel Sail/Docker images these are not always present — verify with php -m before you debug parsing logic.
3. Install: composer require faustddd/symfony-1c-import:^2.0 inside the Symfony sidecar, then register the bundle in config/bundles.php.
4. Read docs/ first. v2.0.0 ships guides on architecture, streaming XML parsing, handlers, security, Messenger workers, and file cleanup. The architecture and handlers docs are the ones that determine how you integrate; read them before writing any import code.
5. First use case: a full commerceML exchange (mode=import, type=catalog then type=offers) into a staging database, driven by a console command or Messenger message. Do not start with incremental offers-only sync — you need a complete catalog before offers mean anything.

Implementation Patterns

Extend the shipped handlers rather than post-processing. CatalogImporter and OffersImporter are designed to be subclassed for application-specific product/offer processing. Override the per-entity hook, map the CommerceML fields you care about, and persist. The bundle explicitly does not persist products or apply pricing rules — that's your job, and it's where most of the real work lives.

final class ProductImporter extends CatalogImporter
{
    protected function handleProduct(array $product): void
    {
        // upsert into your catalog by external 1C GUID, not by name
    }
}

Use CustomImporter for every extra file type. 1C exchanges commonly carry price lists, warehouses, units, and property dictionaries beyond import.xml/offers.xml. v2 gives you one extension point for all of them — register one custom importer per file type instead of bolting logic onto the catalog handler.

Keep the streaming contract end-to-end. The parser uses XMLReader, so the XML document is never fully in memory. That win evaporates if your handler accumulates entities in an array and flushes at the end. Batch your writes (e.g. 500–1000 rows) inside the handler and flush as you go.

Bridge to Laravel deliberately. Pick one seam and stick to it:

// Laravel side: consume what the Symfony sidecar published
class SyncProductFromOneC implements ShouldQueue
{
    public function handle(): void
    {
        Product::updateOrCreate(
            ['one_c_guid' => $this->payload['guid']],
            $this->payload,
        );
    }
}

Upsert on the 1C GUID, never on name/sku — 1C renames things freely.

Queue the whole import. A full catalog exchange is a long-running job. On the Symfony side that's a Messenger worker; on the Laravel side it's a queued job. Either way, run it out-of-band from the HTTP request that accepts the 1C upload — the exchange endpoint should acknowledge fast and enqueue.

Own the file lifecycle. Download → verify → unzip → parse → clean up. Wire docs/'s file-cleanup guidance into a scheduled task so import archives and extracted images don't silently fill the disk.

Gotchas and Tips

• v2.0.0 is a major bump. The release notes advertise new capabilities but do not enumerate removals. If you have any v1 code, diff your subclasses against the new CatalogImporter/OffersImporter signatures before upgrading — the whole point of v2 is that these classes became extension points, which usually means their internal structure moved.
• ZIP errors are now explicit — catch them. Failures opening archives throw rather than degrade. Wrap the unpack step and treat a corrupt/partial upload as a retryable failure, not a crash of the worker.
• Exchange auth is session-based. The improved authorization/session handling means 1C is holding a session across the checkauth/init/file/import cycle. If your sidecar runs on more than one node, you need sticky sessions or shared session storage, or 1C will get bounced mid-exchange. Also make sure no proxy or Laravel middleware strips Set-Cookie on the endpoint.
• Restart workers on deploy. Long-lived Messenger workers cache code; a deploy that changes importer classes will keep executing the old ones. Mirror Laravel's queue:restart discipline in your Symfony deploy script.
• Idempotency is on you. 1C will resend the same catalog. Design handlers so re-running an import is a no-op — upsert, don't insert; guard deletions behind an explicit "full sync" flag.
• Streaming doesn't mean cheap. Memory is bounded for the XML parse, but images and binary properties from the archive are not — store them off-box and keep only paths in your models.
• Do not expect Laravel conveniences. No config/1c-import.php, no php artisan commands, no model events. Everything is Symfony DI: tag your custom importers, wire them in services.yaml, and inject via constructor.
• Business logic stays yours. The bundle stops at "here is a parsed product/offer." Pricing rules, tax mapping, stock reservation, and publishing to the storefront are outside the package — budget for that work; it dominates the integration timeline.