Core Framework Laravel Package

Getting Started

The first thing a Laravel developer must internalize: this is not a Laravel package. Despite the Composer-installable name, uvdesk/core-framework is a Symfony bundle — Twig views, Doctrine ORM entities, a Symfony DI container, Symfony HTTP kernel, Symfony Messenger (not Laravel queues), and config/bundles.php registration. There is no service provider, no facade, no Eloquent model, no Blade, no php artisan. You cannot composer require uvdesk/core-framework into an existing Laravel app and get a helpdesk. Plan for one of two shapes:

1. Standalone Symfony app — install the UVDesk skeleton project, which pulls core-framework plus its sibling bundles (automation/workflow, API, mailers). This is the supported path and what you should default to.
2. Backend service — run UVDesk as its own deployable and treat it as a helpdesk service your Laravel app talks to over webhooks (added in v1.1.7) and HTTP. For most Laravel shops this is the correct answer.

Prerequisites to verify before writing code: composer.json in the target tag for the PHP/Symfony version matrix, a MySQL/Postgres database, outbound SMTP, and a queue worker (Symfony Messenger) — the v1.1.7 webhook dispatch and notification mail both assume it.

Where to look first, in this order:

• CHANGELOG-1.1.md and the tagged release notes — v1.1.7 is the current line and carries three security fixes plus behaviour changes.
• Entity/ and Repository/ — the domain model. Expect a User base entity with Agent and Customer descendants (single-table style inheritance), Ticket, Thread, TicketType, SavedReplies. This is where you learn the actual schema semantics.
• Resources/config/ — routing, DI service definitions, Doctrine mappings, and the bundle's default config tree. This is your real "config quirks" reference.
• Controller/ — the agent/customer surfaces and the permission checks that v1.1.7 tightened.
• Resources/views/ — Twig templates; these are the override surface for UI work.

Your first use case, concretely: install the skeleton locally, create a super-admin + agent, raise a ticket through the customer portal, reply as an agent, then confirm the webhook fires on ticket create. That single loop exercises the entity graph, the mailer, the permission layer (admin vs agent vs customer), and the one integration primitive a Laravel app actually consumes.

Implementation Patterns

Treat webhooks as your primary integration boundary. This is the highest-leverage pattern for a Laravel team: build a Laravel controller as the receiver and let UVDesk push ticket-create and reply events. Validate the payload, persist into your own tables, dispatch a Laravel job. Do not poll the helpdesk database — you'll couple yourself to Doctrine schema internals that shift between releases. The release notes say webhook notifications fire "with all details" on ticket create and replies; treat the payload as untrusted input (it's a PHP app serializing entities — assume PII is in it and scrub before it hits logs or third-party systems).

Fork-and-override, don't fork-and-edit. Symfony gives you two clean levers: (a) override Twig templates by placing a same-named template in templates/bundles/<BundleName>/… in the host app — highest-precedence and survives composer update; (b) decorate services via services.yaml rather than editing vendored classes. Any customisation made inside vendor/ will be destroyed on upgrade and is the #1 source of silent drift.

Extend entities with inheritance, not migrations. UVDesk's user model uses class hierarchy. Adding fields to Agent or Customer should follow the same Doctrine inheritance mapping the bundle already uses, in your bundle, so upstream migrations don't collide with yours. Never hand-edit a vendored entity.

Event subscribers over controller patching. Ticket lifecycle work (assign on create, tag on reply, sync to CRM) belongs in a Symfony EventSubscriber listening to the dispatched ticket events. This keeps the logic in your own bundle, testable in isolation, and — critically — off the request path if you push the heavy work to Messenger.

Port the mental model, not the code. When you do want helpdesk behaviour inside Laravel, don't copy Doctrine entities. Translate the concepts: Ticket has many Threads; Thread has an author (agent or customer) and a visibility (public reply vs internal note — v1.1.7 added colour-coded internal notes, which confirms notes are a first-class visibility flag); Ticket has a type and status; SavedReplies are shared, with admin/super-admin visibility scoping. That conceptual map is worth more than the source.

Sequence your integration work: HTTP/webhook receiver first (thin, idempotent, queued), then read-only ticket mirror for your own dashboards, then write-back only if you genuinely must. Write-back is where you inherit the privilege semantics and security posture of someone else's bundle.

Gotchas and Tips

License is OSL-3.0, not MIT. Open Software License 3.0 is a reciprocal/copyleft-flavoured license. Internal use is fine; distributing a derivative work triggers source-disclosure obligations. If you're building a commercial product on top, get this reviewed before you architect around it — this is a bigger deal than any technical gotcha in this list.

The v1.1.7 security fixes are behaviour changes. XSS, an access-privilege defect, and saved-replies vulnerabilities were fixed in one release. Privilege fixes routinely tighten access, which means agents who previously saw saved replies or agent-access details they shouldn't have will lose that visibility. QA this explicitly — agent vs admin vs super-admin — and pre-brief the service desk, because your first post-deploy tickets will be "I can't see X anymore."

Webhook egress is an SSRF-shaped surface. The app now makes outbound HTTP calls to URLs an admin configures. Enforce a URL allow-list, hard timeouts, capped retries, and a dead-letter path. If it runs synchronously on the reply path, a slow endpoint becomes a slow helpdesk.

Remote image embedding in emails (new in 1.1.7) moves image bytes to the recipient's client. Expect blocked images in enterprise inboxes and corporate proxies, and expect privacy questions — remote images are a tracking vector. Design the templates to degrade to alt text.

Migrations are the deploy risk. The release bumps the doctrine-migration dependency, and rating/note-colour/saved-reply changes almost certainly add schema. Doctrine migrations are not Laravel migrations — no --pretend safety net you'd recognise, reversibility is unconfirmed, and ALTER on a large tickets table can lock. Take a snapshot, run against a production-like clone, and time it.

Stale caches and stale published views are the silent failures. After upgrade: cache:clear, assets:install/asset rebuild, and re-check any template overrides in templates/bundles/. Several 1.1.7 items are Twig-level; if your host app overrode those views, the "new feature" simply won't appear and you'll waste a day debugging nothing.

Version pin and upgrade on a cadence. Three security fixes in one minor release tells you the cadence is real. Pin the exact tag, and diff the changelog on every bump.

Debug with Symfony tooling, not Laravel instincts: debug:router, debug:container, debug:event-dispatcher, and the profiler. There is no Telescope; Xdebug on the ticket service is your step debugger.

Small ecosystem, no Stack Overflow safety net. ~74 stars and effectively zero dependents means you are reading source, not searching for answers. Budget for that. Subscribe to the repo's releases rather than relying on community write-ups.

Translations partial-fallback is a UX trap. Portuguese landed in 1.1.7; if coverage is incomplete, customer-facing strings will flip to English mid-flow. Audit before shipping a localised portal.