Advs Module Laravel Package

Getting Started

• Install via Composer into a Visiosoft/OpenClassify (PyroCMS Streams) application: composer require visiosoft/advs-module. This package is not a standalone Laravel package — it assumes the visiosoft/streams-platform addon runtime is present. There are zero dependents and no README, so treat the source as the spec.
• Register the module. In a standard Streams install it lives under addons/visiosoft/advs-module/. Ensure Visiosoft\AdvsModule\AdvsModuleServiceProvider is listed in config/app.php (or that the addon is enabled via php artisan addon:list / the admin Addons screen). Auto-discovery is unreliable for addons.
• Publish + migrate. Run php artisan addon:publish visiosoft.module.advs followed by php artisan migrate. Addon migrations are namespaced and run against the same DB as core Streams tables (streams_streams, streams_fields, streams_assignments).
• Where to look first, in order:
  1. src/AdvsModuleServiceProvider.php — registers routes, bindings, view namespaces, and the addon manifest.
  2. migrations/ — this is the real schema documentation. Look for the advs stream creation, field definitions (title, price, description, category), and field assignments.
  3. src/Advs/ — the Streams-backed model/repository/form/table builder classes.
  4. resources/views/ — Blade partials for listing and detail views show what data shapes are expected.
• First use case: open /admin/advs and create a listing (advert). Then read it back programmatically via the Streams repository (see Implementation Patterns). That single round-trip validates the migration, field assignment, and view wiring end-to-end.

Implementation Patterns

• Streams, not Eloquent. Everything in ADV — listings, categories, locations — is a Streams stream with fields and assignments. Day-to-day work means using the Streams repository, criteria, and form/table builders rather than raw Eloquent. Query via the module's repository class (typically AdvsRepository) and Streams::entries('advs').
• CRUD through form builders. Build a FormBuilder bound to the advs stream for create/edit screens, and a TableBuilder for admin listings. This is idiomatic PyroCMS and keeps validation, field rendering, and permissions consistent with the rest of the platform.
• Repository + criteria for filtering. Listings are filtered by category, city, price range, etc. Compose Criteria classes (e.g., AdvsByCategory, AdvsOrder) and push them onto the repository rather than writing SQL. This is where "day-to-day" leverage actually happens — new filters are new criteria classes.
• Extend via custom fields, not schema edits. To add a field (condition, mileage, dimensions), register a new field type or assignment through the addon's seeder/migration, then expose it in the form and table builders. Never alter core Streams tables directly.
• Hooks after create/update. Use Streams Entry events (EntryWasCreated, EntryWasUpdated) or model observers to trigger downstream actions — notifications, index updates, geocoding — rather than overriding controllers.
• Blade integration. Include the module's partials directly: @include('visiosoft.module.advs::partials.listing', ['advs' => $advs]). Publish views to override: php artisan vendor:publish --tag=advs-views.
• Routes. The module registers admin routes and likely front-end routes in its service provider. Add new public endpoints by extending the controller, not by adding routes to routes/web.php — keep addon routing scoped.
• Seeding reference data. Categories and location hierarchies ship as seeders. If you need a custom taxonomy, write a new seeder that uses Streams' entry API so it survives reinstalls.
• Composition with sibling modules. In OpenClassify, advs-module composes with profile, categories, and payments modules. Prefer joining via those modules' streams and their Streams relations rather than duplicating data.

Gotchas and Tips

• No documentation, near-zero adoption. Stars = 0, dependents = 0, single release (2024-03-28). Budget time for reading migrations and view files; treat every assumption as needing verification.
• Addon cache is aggressive. Field assignments and stream definitions are cached. After changes run php artisan addon:reinstall visiosoft.module.advs --force (or the equivalent in your Streams version), then clear application cache. A stale streams_assignments table is the #1 cause of "my new field doesn't show."
• Migrations are addon-scoped, not vanilla Laravel. php artisan migrate:rollback acts differently for addon migrations; rollback in a local environment and re-migrate rather than editing already-run migrations.
• Don't confuse advs-module with the broader OpenClassify platform. This package is a fragment; features like image uploads, payments, and moderation may live in sibling modules. Check the parent repo (openclassify/*) before reimplementing.
• Service provider auto-discovery does not apply. Explicitly require the provider, and after deploy confirm with php artisan addon:list | grep advs.
• Version pinning matters. With one release and an active upstream platform, pin both visiosoft/advs-module and visiosoft/streams-platform to known-good versions in composer.json; a platform bump can break field assignment loading.
• Debugging tips: inspect streams_fields and streams_assignments rows directly to confirm the stream is wired; enable query logging in local; log in storage/logs/laravel.log since addon errors are often swallowed by Streams' exception handling.
• Extension points: publish config (php artisan vendor:publish --tag=advs-config) to change defaults, and prefer new Criteria classes plus custom field types over editing vendor files. Any change to vendor code will be lost on the next composer update.
• Testing. There is no test suite to lean on. Write feature tests that hit /admin/advs and assert on Streams entries — this is the only reliable regression net given the package's state.