Laravel Gitscrum Laravel Package

Getting Started

This release (1.1.0) is a feature release on top of the initial line — no breaking changes are advertised, so upgrading from 1.0.x should be a composer update plus re-publishing config and running migrations if new columns were added for labels/sprints.

Minimal setup:

1. composer require <vendor>/<package> (or bump to ^1.1).
2. Publish assets: php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>" — check for config/, migrations/, and any seeder stubs.
3. php artisan migrate — the changelog mentions "Configuration for tests and seeders", so a seeder is likely expected for local data. Run it in local/dev only.
4. Register the package's routes (or confirm auto-discovery) and hit the issues index.

Where to look first:

• config/<package>.php — new toggles for private-mode sprints and page-speed behaviour likely live here.
• routes/web.php / routes/api.php — the AJAX issue-creation endpoint added in this release.
• IssueController@index — refactored in 1.1.0; this is the method whose response shape most likely changed.
• The Issue, Sprint, and label/filter models plus their sync service.

First use case: list issues filtered by label, then create an issue through the AJAX endpoint from your own Blade form. That exercises the two headline features (filter labels by user stories, AJAX issue creation) end-to-end.

Implementation Patterns

Filtering by label / user story. The new "filter labels by user stories" capability suggests scoped queries rather than raw whereHas. Prefer composing the filter through whatever query builder/scope the package exposes so you stay compatible with future refactors:

$issues = Issue::query()
    ->forUserStory($story)
    ->withLabels($labelIds)   // verify exact scope names on the model
    ->latest()
    ->paginate();

Keep your own controller thin — pass validated filter input straight to the scope.

AJAX issue creation. The 1.1.0 endpoint returns JSON rather than a redirect. Two viable patterns:

• Package-owned form: post to the package route with fetch/axios, handle the JSON validation errors (422) and re-render field errors.
• Your own wrapper: keep your form, but call the package's service/action class so validation and label attachment rules stay in one place.

Include X-CSRF-TOKEN and Accept: application/json; without the Accept header you'll get an HTML redirect back instead of a JSON error body.

Sprint sync without detach. The new "sync without detach" behaviour maps to syncWithoutDetaching() semantics on the sprint↔issue pivot. Use it when you're adding issues to a sprint from a bulk action and must not remove issues already attached. Reserve the detaching sync() for reconciling an explicit, authoritative list (e.g. drag-and-drop reorder where the payload is the complete sprint).

Private-mode sprints. Treat this as an authorization concern, not a display one. If you expose sprint data through your own controllers or API resources, replicate the package's visibility check — an is_private flag filtered only in the package's index leaves your custom endpoints leaking.

Page speed integration. "Add laravel page speed" usually means middleware. If you're on the package's defaults, ensure the middleware is registered in the web group and that its position relative to StartSession/Authenticate is deliberate — page-speed minifiers that rewrite HTML can break CSRF meta tags and inline JS (including your AJAX form).

Sprint/issue integration. If sprint data is user-scoped, follow the package's pattern of resolving the current user in the controller (not in the model) so queued jobs and console commands don't accidentally fall back to a null user.

Gotchas and Tips

• Refactored IssueController@index is the highest-risk change. If you've published or overridden the controller, or your frontend parses the index response, diff against the vendor version before deploying. The refactor is the most plausible source of an accidental response-shape change in a minor release.
• syncWithoutDetaching is additive only. It will not remove stale attachments. If an issue was moved out of a sprint elsewhere, this call won't clean it up — plan a separate reconciliation path or you'll accumulate orphaned pivot rows.
• Private sprints + caching. If you cache sprint listings, key the cache by user (or by the visibility scope), otherwise a private sprint cached for an admin will surface for other users.
• AJAX endpoint auth and validation. Confirm the new route sits behind the same middleware as the web form. A JSON endpoint added for convenience is an easy place to lose the auth middleware. Also check whether validation errors return 422 with a errors bag or a flat message — your JS error handler depends on it.
• Test/seed configuration. The new testing config probably registers a separate DB or seeder set. If you have your own phpunit.xml, compare it against the published one; package-provided seeders running in your test suite can silently change fixture counts and break assertions.
• Seeding order matters with labels and user stories: labels attached to issues before the pivot/lookup tables are seeded will fail quietly or leave issues unlabeled. Run the package seeder after migrations and before any of your own data seeders that reference labels.
• Page-speed middleware vs. debugging. Disable it in local/testing (or exclude it via config) — HTML minification mangles stack traces, Livewire/Alpine payloads, and Debugbar output, and you'll spend an hour blaming your own Blade.
• Unused-variable cleanup is cosmetic but signals a controller you may have copied. If you've duplicated package controller code into your app, this refactor is your cue to re-sync or, better, extract an action class and stop copying.
• Upgrade checklist: bump constraint → composer update → re-publish config and diff → migrate → smoke-test the index filters and the AJAX create endpoint → run your suite with the new test config.