Agenda Contatos Laravel Package

Getting Started

The v1.2.0 release is a compatibility bump: the package is now adapted for MocaBonita 3.3.6.10. That is the single most important fact for onboarding — the package's supported surface is defined by its MocaBonita host version, not by a Laravel version constraint, so the first thing to establish in a new project is which MocaBonita release you are actually pinned to.

Minimal steps:

1. Confirm the host version before anything else:

   composer show mocabonita/* --all | grep -i versions
   

   If the project is not on MocaBonita 3.3.6.10 (or a patch-compatible release), stop and reconcile the constraint first. This package release was published to track that specific host version.
2. Require the package and let Composer resolve against the host:

   composer require <vendor>/<package>:^1.2
   

3. Publish and inspect configuration/migrations before running them:

   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   php artisan migrate --pretend
   

4. Clear the framework caches, since MocaBonita-based packages commonly register menus, routes, and views at boot and will silently serve stale registrations:

   php artisan optimize:clear
   

Where to look first: the package's service provider (registration order relative to MocaBonita's own provider matters), then its config/ file, then any src/Http/Controllers or resource/route definitions that hook into the admin surface. The changelog for this package is thin — one line per release — so treat the provider and config as the real documentation.

First use case: wire the package into an existing MocaBonita admin, confirm the admin panel still boots, then exercise the one or two screens the package adds before touching anything else in the app. Because v1.2.0 is a host-compatibility release, "does the admin still render and do the package's routes still resolve" is the meaningful smoke test, not a feature walkthrough.

Implementation Patterns

Pin the pair, not the package. The recurring pattern in this ecosystem is that the package and MocaBonita move together. Express the relationship explicitly in composer.json so a future composer update cannot silently desynchronise them:

"require": {
    "mocabonita/<host>": "3.3.6.10",
    "<vendor>/<package>": "^1.2"
}

Commit composer.lock. In a package this tightly coupled to a host, the lock file is the actual dependency contract.

Register the package provider after the host provider. MocaBonita exposes extension points (menus, admin routes, view namespaces) that only exist once its own provider has run. Check bootstrap/providers.php / config/app.php ordering, and if the package ships menu or route registration, verify it happens in boot() rather than register().

Isolate the integration behind your own layer. Rather than calling package classes directly from controllers and Blade views, wrap the parts you use:

final class AdminDashboard
{
    public function __construct(private readonly PackageService $service) {}

    public function summary(): array
    {
        return $this->service->summary(); // single seam to swap or mock
    }
}

This is worth the small amount of ceremony precisely because the package's public API is coupled to a fast-moving host — when the next MocaBonita bump lands, you change one class instead of grepping the codebase.

Treat upgrades as a paired workflow. When MocaBonita ships a new version, the sequence is: bump host → run the suite → bump this package to the matching release → re-run → manually click through the admin. Automate the middle steps in CI with a matrix that tests the pinned combination, and add a second job against the next host minor so you learn about breakage from CI rather than from a client.

Smoke-test the admin in CI, not just the unit suite. Host-integration packages fail in ways unit tests miss — a menu entry that no longer registers, a view namespace that collides. A single feature test that authenticates and asserts 200 on the admin root and on each package-provided route catches most of it:

public function test_admin_and_package_routes_boot(): void
{
    $this->actingAs($this->admin())
         ->get('/admin')->assertOk();
}

Gotchas and Tips

The changelog is not a changelog. v1.2.0 says only "Adaptado para a versão 3.3.6.10 do MocaBonita." There is no list of changed classes, no deprecation notices, no migration notes. Assume nothing about backwards compatibility and diff the package source between tags before upgrading anything that matters:

composer require <vendor>/<package>:1.1.* --prefer-source
diff -r vendor/<vendor>/<package>/src <(git -C /tmp/pkg show 1.1.0:src)

A host-version bump can change behaviour you never touched. Because the release exists to track MocaBonita 3.3.6.10, the risk is not in this package's diff — it is in the host's. Read the MocaBonita release notes for the corresponding version, and pay attention to anything touching routing, view namespaces, auth guards, or asset publishing, all of which are common breakage points in admin-panel packages.

Beware silent provider-registration failures. If the package registers menus or routes during boot and the host provider has not run yet, you get an empty menu with no error. Symptom: admin loads, package screens are absent. Fix: provider ordering in bootstrap/providers.php. Debug by dumping the registered route list:

php artisan route:list --path=admin -v

Caches mask registration changes. config:cache and route:cache freeze the boot-time state. After every version change, run php artisan optimize:clear before concluding anything is broken — and never debug a menu problem with cached config.

Published assets and views drift. If you published the package's views or assets to resources/views/vendor/... or public/vendor/..., an upgrade will not overwrite them. That is usually what you want, but it also means host-side template changes silently fail to reach your app. Keep a short note of what you published and re-diff after each bump; in most projects, prefer overriding at the app layer over republishing.

Extension points are the safer bet than subclassing. When you need to change behaviour, look for the host's documented hooks (menu, permission, and view registration) before extending the package's classes directly. Subclassing tightens your coupling to internals that this release demonstrates are version-sensitive.

Version-constraint hygiene. If the package declares a MocaBonita constraint like ^3.3, a future 3.4 could install and break you without any signal. If your application's stability matters, replace the constraint with an explicit 3.3.6.10 in the root composer.json and let the lock file carry the rest.

Escalation path. This assessment is based on a single release note; there is no prior evaluation of the package on record and no usage data. Treat the above as a conservative starting position rather than a settled verdict. Once a project has run v1.2.0 against MocaBonita 3.3.6.10 for a release cycle, capture the actual failure modes observed and replace this section with them — that record will be far more valuable than anything inferred from a one-line changelog.