Composer Plugin Laravel Package

Getting Started

This release (v1.1.0) is a Composer plugin, not a Laravel package — there is no service provider, facade, or publishable config. It hooks into Composer's install/update lifecycle for UVdesk-based applications (helpdesk/e-commerce skeletons) to wire newly required uvdesk/* bundles into the project (bundle registration, config/asset placement, post-install hooks). The headline change is improved compatibility with Composer 2 and Symfony Flex 2, which mainly matters at install/build time rather than at runtime.

Minimal steps:

1. Confirm the toolchain. v1.1.0 targets Composer 2 and Symfony Flex 2. Check composer --version and that symfony/flex is ^2.0 in your composer.json. If you still build on Composer 1 or Flex 1, pin the previous plugin release in composer.lock and do not upgrade yet.
2. Allow the plugin explicitly. On Composer ≥ 2.2 the plugin is inert unless permitted:

   {
     "config": {
       "allow-plugins": {
         "uvdesk/composer-plugin": true,
         "symfony/flex": true
       }
     }
   }
   

   Or run composer config allow-plugins.uvdesk/composer-plugin true and commit the change.
3. Look first at the project's root composer.json (extra block, allow-plugins), vendor/uvdesk/composer-plugin/ (the event subscribers that do the work), the generated config/bundles.php / config/packages/* diff after an install, and CHANGELOG-1.1.md linked in the notes.
4. First use case: in a clean checkout, run composer install, then inspect git status — the plugin's output is the set of config/bundle-registration files it wrote. That diff is your mental model of what it does.

Implementation Patterns

• Let the skeleton drive it. In practice you rarely require this plugin directly; it arrives transitively via uvdesk/community-skeleton. Manage its version through the skeleton/composer.lock, not ad hoc.
• Adding a bundle: composer require uvdesk/<bundle> inside a container/CI step that has write access to the project root. The plugin registers the bundle and drops config; commit the resulting config/ changes as part of your PR so the app boots identically without a re-install.
• Docker/CI builds: disable interactivity and pre-authorise the plugin:

  ENV COMPOSER_ALLOW_SUPERUSER=1
  RUN composer config --no-interaction allow-plugins.uvdesk/composer-plugin true \
   && composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
  

  Do the install in the build stage, then run php artisan optimize (or the UVdesk equivalent) after the plugin-generated config files exist.
• Upgrading this release: composer update uvdesk/composer-plugin symfony/flex --with-dependencies, then run a full composer install on a clean checkout (not just dump-autoload) so post-install hooks actually re-run.
• Local development against a fork: use a path repository plus a symlink ("options": {"symlink": true}) and remember the plugin only executes on install/update events — composer dump-autoload alone won't re-trigger it.
• Debugging harness: run composer install -vvv and watch for the plugin's own log lines; combine with composer diagnose when Flex recipe application looks wrong.

Gotchas and Tips

• Silent no-op without allow-plugins. On Composer 2.2+, skipping the prompt (or using --no-interaction in CI) leaves the plugin unexecuted — the install "succeeds" but bundles aren't registered and the app 500s on boot. This is the single most common failure with v1.1.0 upgrades.
• --no-plugins ≠ --no-scripts. --no-scripts skips script events but still loads plugins; --no-plugins disables the plugin entirely. Use --no-plugins only to prove the plugin is the culprit, never in a production build.
• Flex 2 alignment. Flex 2 also requires allow-plugins and Composer 2. Mixing Flex 1 recipes with Flex 2 (extra.symfony.allow-contrib, endpoint changes) can result in config files being written twice or not at all. Keep both plugins on matching majors.
• Plugin output is not idempotent across branches. Generated config is file-based, so switching branches or re-running composer install after manual edits can conflict or overwrite. Keep generated files in version control and review the diff on every dependency bump.
• Cached config hides breakage. After a plugin-driven change, run php artisan config:clear && php artisan cache:clear (or delete bootstrap/cache/*.php) — a stale config.php will make it look like the plugin did nothing.
• composer.lock pins the plugin. Because the plugin affects build output, treat its version like a framework dependency: bump deliberately, in its own PR, with the regenerated config included.
• Extension points: behaviour is configured through extra in the root composer.json and via the plugin's Composer event subscribers in vendor/uvdesk/composer-plugin/src. If you need custom placement of bundle files, prefer overriding at the project level rather than patching vendor/.
• Rollback plan: if the upgrade breaks a build, composer require uvdesk/composer-plugin:<previous> --with-dependencies and keep Composer 2 in place — the earlier line still works on Composer 2, it simply lacks the Flex 2 refinements.

Verdict: v1.1.0 is a compatibility/maintenance release — no breaking API changes for consumers, but it does raise the effective floor to Composer 2 + Flex 2 and makes allow-plugins configuration mandatory. Worth taking now; verify the config diff after upgrading.