Extension Framework Laravel Package

Getting Started

Before writing any code, confirm you are inside a working UVdesk application (the standalone helpdesk project, not just the bundle). The extension-framework is a Symfony bundle that manages the lifecycle of other bundles; it is not useful on its own.

1. Install the framework into the UVdesk app:

   composer require uvdesk/extension-framework
   

   Then register it in config/bundles.php if the recipe did not do so automatically.

2. Look first at the Uvdesk\ExtensionFrameworkBundle namespace — specifically:

   • The abstract extension/bundle base class your package will extend.
   • The ExtensionManager service, which orchestrates install, update, and uninstall.
   • The console commands under Console/Command (uvdesk:extension:install, uvdesk:extension:uninstall, and related subcommands).

3. First use case: scaffold a minimal extension. Create a Composer package whose composer.json declares UVdesk metadata (typically an extra section with the extension name, description, and version), a Symfony bundle class extending the framework's abstract extension, and a services.yaml. Then run:

   composer dump-autoload
   bin/console uvdesk:extension:install <vendor/package>
   bin/console cache:clear
   

   The install command wires the bundle in, runs lifecycle hooks, and publishes assets/config.

4. Read one first-party or community extension end-to-end before building your own — the lifecycle contract is easier to absorb from a working example than from the base class alone.

Implementation Patterns

Package layout. Treat an extension as a first-class Composer package: src/ for PHP, Resources/views for Twig, Resources/translations for locale files, Resources/public for assets, and migrations under migrations/. Keep the bundle class thin — its only job is to declare metadata and, when required, lifecycle behavior.

Extend the abstract extension rather than implementing the interface directly. Override package name, display name, version, and dependencies, and let the framework handle registration. If you implement ExtensionInterface manually you lose the built-in dependency ordering and update plumbing.

Lifecycle hooks. Put migrations, config publishing, and seed data into the install/uninstall/update methods provided by the base class. Prefer idempotent operations (CREATE TABLE IF NOT EXISTS, guarded config writes) because the install command can be re-run. Pair this with Doctrine migrations for schema so uninstall can be reasoned about.

Dependency declaration. When extension B needs extension A, declare it in B's metadata. The manager resolves ordering on install. Avoid implicit runtime dependencies that only show up as a missing-service ServiceNotFoundException at container compile.

Integration into the helpdesk UI. Do not edit UVdesk core templates. Contribute via:

• Event subscribers for request/kernel events and any UVdesk-specific dispatched events.
• Twig Resources/views templates following UVdesk's existing naming so theme overrides still work.
• Menu/route registration through service tags or configuration, rather than hardcoding entries.

Local development loop. Use a Composer path repository pointing at your extension source, so edits are live without re-requiring:

"repositories": [{ "type": "path", "url": "../my-extension" }]

After changes to services or bundle registration, cache:clear is almost always required; after class or namespace changes, dump-autoload -o is.

Versioning workflow. Bump the extension version in its metadata on every release, and test install/update/uninstall in a throwaway UVdesk instance, not your working one. The framework's value is precisely that lifecycle, so an extension that installs but cannot be cleanly uninstalled is effectively broken.

Gotchas and Tips

• Stale container is the #1 failure mode. If an extension "isn't found" or a service "doesn't exist," clear the cache (bin/console cache:clear, and in dev check var/cache/dev) before debugging anything else.
• The install command does not fetch from Packagist. The package must already be installed and autoloadable via Composer. uvdesk:extension:install registers and runs lifecycle, it does not composer require for you.
• Autoload misses after namespace renames. Composer's classmap is cached; run composer dump-autoload and only then re-install.
• Symfony version constraints bite. UVdesk core pins specific Symfony minors; loose constraints in your extension's composer.json can pass CI but fail on a customer's locked install. Mirror core's constraints.
• Uninstall is destructive by default. Decide explicitly what uninstall should delete versus preserve. Data loss on uninstall is a common review rejection — make table drop opt-in or documented.
• Install ordering. Without declared dependencies, install order is not guaranteed. Two extensions touching the same event or the same table can produce order-dependent bugs that only appear on fresh setups.
• Debugging checklist: bin/console debug:container <service>, bin/console debug:router, bin/console debug:event-dispatcher — plus var/log/dev.log. The framework itself rarely logs loudly; failures usually surface as container compile errors or silent no-op hooks.
• Extension points worth knowing: event subscribers, service tags for menu/UI contributions, the abstract extension's lifecycle methods, and Twig template override paths. These are the sanctioned seams — everything else is reaching into internals that will break on upgrade.
• Do not pin to a single framework patch. The last release is dated 2024-12-18 and the project has low activity; assume upgrades are infrequent and plan to test against both the pinned and next-minor versions yourself.
• License note: the framework is OSL-3.0. Verify compatibility with your own extension's license before distributing through the community marketplace.