Activity Comments Api Laravel Package

Getting Started

liberusoftware/activity-comments-api is a presentation adapter, not a domain package. Expect it to contain HTTP controllers, form requests, API resources, and route registrations that sit on top of a sibling domain module (likely liberusoftware/module-activity-comments or similar). Your first job is to confirm what it actually pulls in, because the adapter is useless without the underlying model/service layer.

Minimal setup:

composer require liberusoftware/activity-comments-api

Before running composer update, open the installed composer.json and read its require block. With zero stars and zero dependents, the package is effectively a private/internal module published publicly — it almost certainly declares path or VCS repositories for its sibling modules, and may not resolve cleanly from Packagist alone.

If auto-discovery doesn't fire:

// bootstrap/providers.php (Laravel 11+) or config/app.php
Liberu\ActivityCommentsApi\Providers\ActivityCommentsApiServiceProvider::class,

Where to look first, in this order:

1. composer.json — sibling module dependencies and PHP/Laravel constraints.
2. src/Providers/*ServiceProvider.php — route registration, config merging, container bindings. This tells you the route prefix, middleware group, and which contracts are bound.
3. routes/ — the actual endpoint surface (api.php vs a versioned file).
4. src/Http/Controllers/ — thin adapters; read them to learn which domain actions they call.
5. config/ — publishable config for route prefix, pagination size, and middlewares.

First use case: posting a comment against an activity subject.

php artisan route:list --path=activity
php artisan vendor:publish --provider="Liberu\ActivityCommentsApi\Providers\ActivityCommentsApiServiceProvider"

Then exercise the create endpoint through Sanctum-authenticated requests rather than writing new controllers — the adapter's value is that the endpoint already exists.

Implementation Patterns

Treat controllers as adapters, not logic. The package name says it: requests in, domain calls out, resources back. When you need behaviour that isn't there, add it to the domain module and bind it — don't fatten the adapter.

Route registration and guarding. Register the adapter's routes behind your auth stack, and prefer explicit middleware over trusting the package default:

// routes/api.php — if the package doesn't auto-register
Route::middleware(['auth:sanctum', 'throttle:api'])
    ->prefix('api/v1')
    ->group(base_path('vendor/liberusoftware/activity-comments-api/routes/api.php'));

Polymorphic subjects are the core pattern. Activities and comments attach to a subject (an order, a ticket, a project). Expect morph-map configuration to matter:

// config/activity-comments.php or your AppServiceProvider
Relation::enforceMorphMap([
    'order'   => \App\Models\Order::class,
    'ticket'  => \App\Models\Ticket::class,
]);

Enforce the morph map before the package's service provider boots, or you'll get inconsistent subject_type values written to the DB and unreadable later.

Authorize in policies, not controllers. The adapter will typically call $this->authorize(...) or check a gate. Register policies for your comment/activity models in AuthServiceProvider so the adapter inherits them. This is the correct extension point — it keeps the vendor code untouched.

Compose with the domain module for side effects. If posting a comment should notify watchers, do it with a listener on the domain event rather than editing the adapter:

Event::listen(CommentCreated::class, NotifyCommentWatchers::class);

Testing pattern. Because the adapter is thin, integration tests give the most coverage per line:

public function test_user_can_comment_on_activity(): void
{
    $user = User::factory()->create();
    $activity = Activity::factory()->create();

    $this->actingAs($user)
        ->postJson("/api/v1/activities/{$activity->id}/comments", [
            'body' => 'Looks good.',
        ])
        ->assertCreated()
        ->assertJsonPath('data.body', 'Looks good.');

    $this->assertDatabaseHas('comments', ['user_id' => $user->id]);
}

Assert on the DB, not just the response — the adapter can return a well-formed payload while the domain write silently no-ops.

Pagination contract. Read the resource class to see whether it emits data/meta/links (Laravel resource collection) or a custom envelope. Match it in your frontend once, and centralise the client-side parser — this is the most common source of drift when the adapter updates.

Gotchas and Tips

License is NOASSERTION. This is the biggest risk. Composer will install it, but you have no declared rights to redistribute or modify. Get legal sign-off before shipping it in anything commercial, or plan to treat it as a study reference and reimplement the ~200 lines of adapter yourself. This is usually cheaper than it sounds.

Pin the version exactly. One release, zero dependents, no stars, a future-dated release timestamp. There is no community pressure to preserve BC. Use "liberusoftware/activity-comments-api": "1.0.*" at most, commit composer.lock, and fork into your own VCS if you expect to patch it.

It won't work standalone. "Presentation adapter" means the domain lives elsewhere. Missing migrations, undefined classes, or BindingResolutionException on an action interface almost always means a sibling module isn't installed or its provider isn't registered. Read the adapter's require block and install the whole set.

Config and migration collisions. Publish config once and commit it. If your app already defines comments or activities tables, the package's migrations will conflict or, worse, silently alter your schema. Check vendor/.../database/migrations before running migrate in any environment with existing data.

Route prefix clashes. If you also mount a versioned API under api/v1, two providers registering overlapping paths produce last-one-wins routing that route:list won't obviously flag. Run php artisan route:list --path=comments -v and check for duplicate URIs after every install.

N+1 on the feed endpoint. Activity feeds eager-load comment authors and subjects. Because the adapter owns the query building, you can't fix it with a local with(). Options: cache the endpoint, or bind a custom repository implementation if the provider type-hints a contract rather than a concrete class. Verify by dumping DB::getQueryLog() on a single feed request — if query count scales with page size, this is why.

Debugging checklist. In order: route:list for the endpoint, php artisan about / container make() on the action class to confirm the binding, DB::listen() for the write actually happening, then the resource class for payload shape. Telescope pays for itself here.

Extension points worth knowing. The safe ones are: policies (auth), event listeners (side effects), morph map (subject typing), config (prefix/pagination), and container bindings where the package type-hints interfaces. The unsafe one is editing vendor/ — with no active maintenance, your edits vanish on the next composer update and nobody upstream will merge a fix.

Budget for ownership. Score ~20, no dependents, no license clarity. Adopt this only if you're prepared to fork and maintain it, or if you're using it as a reference implementation for your own activity/comments adapter. The patterns in it are standard Laravel and easy to reproduce; the dependency risk is not.