Agri Gestion Bundle Laravel Package

Getting Started

This is the first assessment for the package, based on the 1.0.0 release notes. The package provides farm/parcel management primitives: parcels, cow entry/exit history, hay entries, providers, articles, and article prices.

Minimal setup:

1. Install via Composer and let Laravel discover the service provider, or register it manually if the package targets older Laravel versions.
2. Publish and review package assets before migrating:

   php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider"
   php artisan migrate
   

3. Inspect the published config, migrations, and models first. Confirm table names, foreign keys, and whether the package assumes a single farm/tenant or supports scoping.
4. Check the package README for route/controller/API exposure. If the package is model-only, you will wire your own controllers, form requests, and policies.

First practical use case: create a Parcel, record cow entries/exits against it, and add hay entries to track feed movement. In parallel, create Provider records, then Article records and ArticlePrice records for supplier pricing.

Day-to-day entry points:

• Eloquent models for Parcel, Cow, Hay, Provider, Article, and ArticlePrice.
• Migration files for relationship and constraint behavior.
• Any published config for table prefixes, model swapping, or feature flags.
• Package events/observers, if present, for cow movement and price changes.

Implementation Patterns

Use the package as a domain layer, not as a full application. Keep your HTTP/UI layer thin and let the package models own persistence.

Common workflows:

• Parcel lifecycle:
  • Create/edit parcels through your own controller or admin panel.
  • Treat parcel deletion as an administrative action. Before deleting, check whether historical cow/hay records should block deletion or be archived.
• Cow movement history:
  • Record entry and exit as separate historical events rather than mutating a single “current parcel” field.
  • Wrap movement operations in database transactions when they also update parcel occupancy or feed totals.
  • Prefer append-only history. If the package exposes edit/delete for history, restrict it in your policy layer.
• Hay entries:
  • Use hay entries as inventory/feed records tied to a parcel.
  • Normalize units in your application layer if the package does not enforce them.
• Provider/article/price management:
  • Seed or import providers and articles first, then attach prices.
  • Treat ArticlePrice as price history: create a new price row for a new effective price instead of overwriting old rows, unless the schema explicitly supports versioning.
• Integration tips:
  • Add form requests around package models for validation, especially around dates, quantities, and foreign IDs.
  • Add policies/gates for create/edit/delete actions; release notes expose CRUD but not authorization.
  • Use API resources or view models if exposing parcel history to end users.
  • If multi-tenant/farm scoping is required, add a global scope or explicit farm_id handling in your own layer after confirming the package schema supports it.
  • Use database seeders for reference data such as providers and articles.
  • Use model observers or domain events to log cow movements and price changes for auditability.

Suggested first integration slice:

DB::transaction(function () use ($parcel, $cow, $data) {
    // Create the cow entry/exit history record via the package model.
    // Update any parcel-level counters in your own application code.
});

Gotchas and Tips

• Historical data vs. deletion:
  • Cow entry/exit history and hay entries are historical records. Deleting a parcel or cow may cascade, restrict, or orphan those records depending on migration constraints. Check foreign keys before exposing delete actions.
• Price precision:
  • Article prices should use decimal columns, not floats. Confirm the package migration uses a money-safe type before relying on it for billing or supplier calculations.
• Price history semantics:
  • The release notes mention create/edit/delete for article prices but not effective dates or versioning. If your business needs price history, add an effective-date column or append-only workflow in your own layer.
• Provider/article dependencies:
  • Deleting a provider that has articles may fail or cascade. Decide whether to use soft deletes, restrict deletion, or null out provider references.
• Single-tenant assumptions:
  • The release notes do not mention farms, tenants, or user ownership. Verify whether records are global. If not, add scoping carefully and consistently.
• Units and quantities:
  • Hay entries and cow movements may not enforce unit consistency. Validate units and quantities at the application boundary.
• Debugging:
  • Use php artisan model:show for the package models, Laravel Telescope/query logs for relationship queries, and migration inspection for constraint behavior.
  • If routes or views are missing, confirm whether the package is model-only and whether you need to publish/register routes.
• Extension points:
  • Prefer publishing config and swapping models via config if supported.
  • Use model observers/events rather than editing vendor code.
  • Keep package migrations untouched after they have run in production; add your own follow-up migrations for indexes, scoping columns, or constraints.
• Release-note caution:
  • 1.0.0 is the first release. Expect API/schema changes before 2.0.0. Pin the version in composer.json and add integration tests around parcel deletion, cow movement history, and article price creation.