Importsynchro Laravel Package

Getting Started

Before composer require, spend 45 minutes reading source. Everything below assumes you've confirmed the package is usable at all — the metadata (GitLab-hosted under point-web/importbundle, bundle suffix, single French description line, zero stars/dependents) points to a Symfony-lineage internal module, not a Laravel package. Do not wire it into a branch until you've answered: is there a composer.json, what does it declare as type, and is there a ServiceProvider or a Symfony Bundle subclass?

Where to look first, in order:

1. composer.json — type (symfony-bundle vs library), require constraints (PHP, laravel/framework, symfony/*), autoload map, and whether it even declares a Laravel version range.
2. Entry point class — grep for extends Bundle (Symfony) vs extends ServiceProvider (Laravel). This single check decides your integration strategy.
3. Any Command/ or Console/ directory — that's your day-to-day surface. Confirm whether commands are Symfony Console commands or Laravel Artisan commands; they are not interchangeable.
4. config/ and Resources/config/ — the field-mapping schema lives here. This is the part you'll actually touch every week.
5. README — French-only is the default expectation. Budget a translation pass for the two or three config keys you'll use.

First use case — keep it deliberately narrow. Pick one entity and one direction (source → DB), e.g. a CSV of products into a single table. Do not attempt bi-directional sync or multi-entity graphs on day one; the unknown error semantics will bury you. Run it against a throwaway database, not a dev environment shared with anyone.

If it is published to a private Composer registry:

"repositories": [{ "type": "vcs", "url": "https://gitlab.com/point-web/importbundle" }],
"require": { "lk/importsynchro": "dev-main#<sha>" }

Pin to a commit SHA, not dev-main. With no release history, a floating branch ref means the package can change under you between composer updates. If it isn't on Packagist or a reachable registry, vendoring the source into app/Support/ImportSynchro is the honest option — you'll be maintaining it regardless.

Implementation Patterns

Adapter-first, always. Define your own interface and make the package one implementation behind it. This is the single highest-value pattern here because it preserves your ability to swap in a hand-rolled importer after the first incident:

interface ImportSynchronizerInterface {
    public function run(ImportSource $source, ImportTarget $target): ImportResult;
}

Everything package-specific (its config array shape, its exceptions, its return types) stays inside that adapter. Your commands, jobs, and tests only see ImportSynchronizerInterface.

If it's a Symfony bundle or standalone CLI, run it out-of-process. Do not fight the container. Invoke it as a worker from a Laravel job:

class RunImportJob implements ShouldQueue {
    public function handle(): void {
        $proc = new Process(['php', base_path('vendor/bin/importsynchro'), '--config=...']);
        $proc->setTimeout(3600)->run();
        // parse exit code + stdout into your own result object
    }
}

This isolates version conflicts, avoids polluting the Laravel container, and gives you a clear process boundary to log and retry across.

Upsert by your own constraint, not the package's. Whatever field-mapping config you write, add a unique index on the natural key (external ID, SKU, partner reference) in your own migration. Treat the package's "synchronization" as best-effort and let the database enforce idempotency. This is the cheapest insurance against duplicate writes you'll ever buy.

Wrap chunking yourself if you can't verify it. The description claims chunked processing; verify in source. If it processes row-by-row synchronously, put your own chunk loop around it — read 500 source rows, call the sync once per chunk, commit, repeat. Never hand it a full file and hope.

Reconciliation as a first-class step, not an afterthought. After every run, compare count(source), count(inserted) + count(updated) + count(skipped), and a checksum on a sample of mapped fields. Persist the result to an import_runs table with timestamps, counts, and the source checksum. This table is what you'll debug from at 2am and what you'll show stakeholders when they ask "is the sync working?"

Dead-letter per chunk. Catch exceptions at the chunk boundary, write the failing rows plus the exception to import_failures, and continue. Unbounded retries against a partner API are how you get rate-limited out of the integration entirely.

Scheduling. app/Console/Kernel.php calls your own Artisan command, which delegates to the adapter. Do not let a package command own the schedule — you want the schedule visible in your repo, with your withoutOverlapping() and onOneServer() guards.

Contract test with fixtures. A single test that runs a 10-row fixture through the adapter and asserts the resulting table state is worth more than any amount of README reading. It's also your only real defence when you eventually fork.

Gotchas and Tips

• The bundle suffix is a warning, not a style choice. Symfony bundles do not auto-register in Laravel, do not use config/ publishing conventions, and often reference Symfony\Component\* which you cannot install alongside Laravel cleanly. Confirm before assuming any of the description's Laravel-shaped claims ("Artisan commands", "Eloquent") are true — those may be aspirational copy.
• No Packagist presence means no SemVer. Even if it's installable via VCS, there are no tags to constrain against. Pin SHAs and record the SHA in your runbook so you can answer "what version are we on?" during an incident.
• French-only docs concentrate knowledge. Whoever reads the source first becomes the single point of failure. Force the issue: an English docs/import-synchro.md in your repo describing the config keys you actually use, written the same week you integrate.
• Migrations are the classic hidden landmine. Grep for Schema:: or Doctrine\ migration files. A package migration that creates or alters a table you already own will either fail loudly on migrate or — worse — silently change a column type. Read every migration before running it.
• Config key naming will be inconsistent and French. Expect keys like champs, correspondance, source. Wrap the package config in your own config file (config/imports.php) so your app's environment variables don't leak French field names into .env.
• Transaction boundaries are unknown until proven. Assume the package commits per-row and that a mid-run crash leaves partial state. Test it: kill the process halfway through a run and inspect the table. The result tells you whether you need a staging table + swap pattern.
• Idempotency semantics are unverifiable from metadata. Run the same fixture twice. If row counts double, you need your unique index before the first production run, not after.
• Extension points probably don't transfer. If it exposes Symfony's event dispatcher or a compiler pass for custom field mappers, that hooks into a container you don't have. Plan to extend by wrapping the adapter (post-processing hooks in your own code), not by plugging into the package's internals.
• Debugging approach that works here: run with one source row, dd() the mapped attribute array before it hits the database, compare to what you expect. Most mapping bugs are visible at that boundary and nowhere else. Add a --dry-run shim to your own command if the package doesn't provide one.
• Escalation path is point-web or nothing. There is no issue tracker activity, no Stack Overflow footprint, and no dependents to compare notes with. If your team doesn't have an existing relationship with that group, price the integration as "we will own this forever" before you start — and re-read that sentence before merging the PR.