Poker Planner Laravel Package

Getting Started

symfinity/poker-planner is a Laravel package for running planning-poker / scrum-estimation sessions inside your application. This is a v0.1.x patch release (v0.1.3), so treat the API as unstable and pin your version in composer.json ("symfinity/poker-planner": "0.1.*").

First steps:

1. Read the source over the README. At this maturity level the README is often thinner than the code. Start with the package's src/ service provider, then the routes/ (or route registration in the provider) and models — that tells you the real surface area faster than docs.
2. Check the CHANGELOG (https://github.com/symfinity/poker-planner/blob/v0.1.3/CHANGELOG.md) before upgrading. A patch bump on a 0.x package can still contain behavioural fixes, and the linked changelog is the only authoritative record.
3. Publish and inspect config/migrations, if the package ships them:

   php artisan vendor:publish --provider="Symfinity\PokerPlanner\PokerPlannerServiceProvider"
   php artisan migrate
   

4. Confirm auto-discovery — check composer.json of the package for extra.laravel.providers. If present you don't need to register the provider manually; if not, add it in bootstrap/providers.php.

First use case: create a single estimation session (a "room") tied to a story/ticket, join as a participant, cast a vote, and reveal. Get that single vertical slice working end-to-end before wiring it into real backlog data.

Implementation Patterns

• Session-per-story. The natural unit is one planning session mapped to one backlog item. Persist the story reference (an external ticket ID rather than a FK) so the package doesn't couple your domain models to it.
• Wrap the flows in your own service/action layer. Don't call package classes directly from controllers throughout your app. Create thin wrappers (e.g. a PlanningPoker service) so that when the 0.x API shifts you have one place to update.
• Voting via your existing auth. Bind participants to your User/auth model in config or via a resolver if the package supports it. If it only stores participant names, map them back to users yourself for auditability.
• Broadcast if available. Planning poker is inherently real-time; check whether the package ships events/broadcasting. If it does, wire up Echo/Pusher and listen for reveal/vote events rather than polling. If it doesn't, poll on an interval and keep the reveal action explicit.
• Route integration. Mount the package routes under an authenticated middleware group (web + auth) and, if needed, gate access with a policy so only room participants can reveal.
• Testing. Feature-test your own wrappers, not the package internals — package behaviour may change between patches. Use RefreshDatabase with the published migrations so tests exercise the real schema.

Gotchas and Tips

• It's pre-1.0. SemVer permits breaking changes even in patch releases from the maintainer's perspective (and many do it regardless). Always diff the changelog and skim git log between tags before bumping in production.
• Migrations are published, not tracked. Once published into database/migrations, upstream schema changes won't apply automatically. Re-publish to a new timestamped file and migrate; don't edit the existing one in place.
• N+1 on participants/votes. Loading a session with its participants and votes is the classic N+1 spot — eager-load (with('votes')) in your wrappers.
• Reveal timing / clock skew. Vote visibility depends on a "revealed" flag or timestamp. Test the reveal boundary; don't rely on client clocks.
• Config quirks. Check the published config for anything about route prefix, middleware, table names, and user model. Table-name collisions with existing tables are a common 0.x surprise — override in config before migrating.
• Extension points are limited at 0.1.x. Prefer wrapping and composing over forking. If you must override behaviour, bind a subclass in the container rather than editing vendor files.
• Debugging. If routes 404, run php artisan route:list to confirm the provider registered and check the middleware group — an unauthenticated test hitting a web-only route is the usual culprit.

Given the patch-level, changelog-only release, there is nothing in v0.1.3 that changes the above guidance — pin to 0.1.*, watch the changelog, and keep integration behind your own wrappers.