Core Laravel Package

Getting Started

This is the first beta of SeviaFlow Core. There is no stable API contract yet, so treat this release as an evaluation artifact rather than a production dependency.

1. Install the package from its published source (Composer or VCS, depending on how the beta is distributed). Pin the exact beta version in composer.json — do not use a floating constraint.
2. After installation, check the following in order:
   • The package README and any docs/ directory.
   • The service provider(s) registered by the package. Look for bindings, singletons, facades, and publishable assets.
   • Any config file published via vendor:publish. Read every key and default before changing anything.
   • Migrations, if the package persists workflow state. Run them only in a disposable local/staging database first.
3. Run the package’s own test suite if it ships one, or write a single smoke test that boots the application and resolves the package’s main entry point from the container.
4. First practical use case: define the smallest possible flow — one trigger, one step, one completion condition — and execute it inside a Laravel feature test. Do not start with a multi-step, queued, or event-driven flow. The goal is to confirm the package boots, resolves its dependencies, and completes a trivial lifecycle before you invest in modeling real business processes.

Because the release notes do not describe the public API, the first hour should be spent mapping the package surface: contracts, facades, config keys, database tables, events, and jobs. Everything else follows from that map.

Implementation Patterns

SeviaFlow Core appears to be a workflow/flow engine for Laravel, but the beta notes do not document its API. The patterns below are the ones that matter for day-to-day use once you have confirmed the package’s actual surface.

• Wrap the package behind your own service layer. Do not call package classes directly from controllers, jobs, or Livewire components. Create a small application-level service (e.g., App\Workflow\FlowRunner) that depends on the package’s contracts or facade. When the beta API changes — and it will — you change one class instead of every call site.
• Model flows as first-class application objects. Keep flow definitions in dedicated classes or config files under app/ or config/, not inline in controllers. This makes flows testable and keeps package-specific syntax out of your domain code.
• Use Laravel’s container for substitution. If the package binds interfaces, bind your own test doubles or decorators in a service provider. In tests, swap the real runner for a fake that records transitions rather than executing side effects.
• Integrate with queues deliberately. If the package supports queued steps, start with the sync driver in tests and a dedicated queue in staging. Never let a beta workflow engine share a queue with critical production jobs during evaluation.
• Persist and assert state transitions. If the package writes workflow state to the database, write feature tests that assert the expected rows after each transition. Treat the package’s tables as internal, but read them in tests to verify behavior.
• Emit and listen to domain events, not package events. If the package dispatches events, translate them into your own application events inside the wrapper. This keeps your listeners stable if the package renames or removes events.
• Use database transactions in tests. Wrap flow-execution tests in DatabaseTransactions or RefreshDatabase so beta migrations and state writes do not leak between tests.
• Keep a compatibility shim. If the package exposes a facade, alias it in config/app.php only if necessary, and prefer constructor injection of the underlying contract. Facades are convenient but harder to replace during a beta.

Gotchas and Tips

• The beta is explicitly unstable. The release notes state that APIs and behavior may change before 0.1.0. Pin the exact version, read every release note, and do not deploy this to production without a rollback plan.
• No upgrade path is documented yet. Before writing significant code, check whether the package publishes an upgrade guide or CHANGELOG. If not, keep your integration thin enough that a breaking change is a one-file fix.
• Config caching can hide beta defaults. Run php artisan config:clear after publishing config. If the package reads config at boot time, a cached config from a previous version can produce confusing failures.
• Migrations are the highest-risk surface. Beta packages often revise schema between releases. Run migrations against a disposable database first, and never run migrate:fresh on a database containing anything you care about.
• Watch for Laravel and PHP version constraints. Check the package’s composer.json for illuminate/* and php requirements. A beta released against Laravel 11 may not install cleanly on Laravel 10 or 12.
• Debug with Laravel’s standard tools first. Use php artisan about, php artisan package:discover, Telescope (if available), and application logs. If the package dispatches events or jobs, log them in a local listener before guessing at internal behavior.
• Inspect extension points before you need them. Look for contracts, macros, custom step handlers, or resolver callbacks. If the package has no extension points, assume you will fork or wrap it heavily when your requirements diverge.
• Avoid relying on undocumented internals. Beta packages often expose public classes that are not intended as API. If a class is not referenced in the README or a contract, treat it as private.
• Budget for missing documentation. The release notes are brief, so expect to read source code. Start with the service provider and the main facade/contract; that usually reveals the intended entry points faster than browsing directories.
• Re-evaluate at stable 0.1.0. This assessment is based solely on the beta release notes. Once stable documentation and a changelog exist, revisit the integration patterns and remove any temporary shims that are no longer needed.