Sulu Media Sync Bundle Laravel Package

Getting Started

• Know what you're installing: ahmed-bhs/sulu-media-sync-bundle is a Sulu CMS bundle (Symfony), not a Laravel package. There is no service provider auto-discovery, no php artisan, no publishable config/*.php. If your app is Laravel-only, this package is not usable without a Symfony/Sulu host.
• Install with the beta flag. The tag is v0.1.0-beta.2, so the constraint must opt into beta stability:

  composer require ahmed-bhs/sulu-media-sync-bundle:^0.1@beta
  

  Without @beta Composer will silently fail to resolve (no stable release exists yet).
• Register the bundle in your Sulu app's config/bundles.php (Sulu skeleton convention). Confirm the exact bundle class name from the README rather than guessing.
• Apply the schema change. The README ships php bin/console doctrine:schema:update --force, but for anything beyond a throwaway dev box, run doctrine:migrations:diff then doctrine:migrations:migrate so the schema delta is reviewable and reversible.
• Where to look first: the README (now English, so it's actually readable), then the bundle's DependencyInjection/Configuration.php for the real config tree, then the admin translation files for the label surface.
• First use case: configure a source, run the bundle's sync console command, and verify the imported media appears in the Sulu admin media section. Do this on a dev database before wiring anything scheduled.

Implementation Patterns

• Config lives in YAML, not PHP. Wire it in config/packages/ (e.g. a dedicated sulu_media_sync.yaml) and keep environment-specific values in .env placeholders, matching normal Symfony bundle conventions.
• Run sync as a console command, not a request. This is the natural integration point: a cron entry or a Sulu/Symfony scheduler task invoking the bundle's command, rather than triggering sync from a controller. Wrap it in a lock (flock or symfony/lock) so overlapping cron runs can't double-import.
• Treat the beta constraint as a real constraint in CI. Pin 0.1.0-beta.2 in composer.json and commit the lock file. ^0.1@beta will happily float to the next beta.
• Override admin labels, don't fork them. Default admin labels are now English and the French translations are retained as a UI locale, not a source language. If you need different wording, override through Sulu's translation mechanism (project-level translation resources / translation domain override) instead of editing vendor files — vendor edits vanish on the next composer update.
• Stage-gate before production. Beta + a schema-mutating install step means: install on a scratch environment, inspect the generated migration, then promote. Don't run schema:update --force against a database with real content.
• Keep a rollback path. Snapshot the media tables (or the whole DB) before the first sync, since you're trusting an unproven beta to write into Sulu's media storage.

Gotchas and Tips

• Packagist tag caching bit beta.1, and it can bite you too. The release notes are explicit: v0.1.0-beta.1 on Packagist is pinned to a commit that still contained the French sources, because Packagist caches tag→commit mappings and does not follow a moved tag. If you already installed beta.1, a plain composer update may not move you. Force the version explicitly:

  composer require ahmed-bhs/sulu-media-sync-bundle:0.1.0-beta.2 --with-dependencies
  

  and verify with composer show ahmed-bhs/sulu-media-sync-bundle. Stale French comments/labels in vendor/ is the tell that you're still on the cached beta.1 commit.
• doctrine:schema:update --force is not a production migration strategy. It diffs and applies blindly; it will not warn you about dropped columns or data loss. Generate a migration and read it first.
• No stable tag means no stability guarantees. Expect breaking changes between 0.1.0-beta.x releases, and expect the config tree keys to move. Re-read Configuration.php after every bump rather than assuming your YAML still validates.
• Behaviour between beta.1 and beta.2 is identical — this release is a language/localisation change only. So: no migration work is needed to move from beta.1 to beta.2, and equally, beta.2 fixes nothing functional. If you hit a bug on beta.1, upgrading won't help.
• Debugging: run the sync command with -vvv, and clear the cache (bin/console cache:clear) after changing translations/config — Sulu's admin translations are cached, so label overrides often look broken until you clear.
• Extension points to check before writing glue code: the bundle's config tree (for source/target mapping), its console command options, and its translation domain for admin labels. If the config tree doesn't expose what you need, prefer a decorator over the bundle's service over copying its code — the latter will drift immediately given the beta cadence.
• Framing note for the team: the only Laravel-adjacent path here is running Sulu as a separate service and having your Laravel app talk to it over HTTP/queue. That's a significant architectural decision, not a composer require. Decide that explicitly rather than discovering it at install time.