Laravel 10 Starter Kit Laravel Package

Getting Started

This release adds the package's core Address Information feature, so treat v1.1.0 as the first version where you actually have something to use.

1. Install and publish.

   composer require <vendor>/<package>
   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   

   Publish tags are usually config, migrations, and sometimes views/lang. Publish migrations before running anything.

2. Run the migration — this is the headline change.

   php artisan migrate
   

   The release notes call this out explicitly. The new address table(s) are the entire feature; without this step the package's models will throw "table not found" the moment you touch an address.

3. Look here first, in this order:

   • database/migrations/*_create_addresses_table.php — column names, nullability, and whether the owner relation is a foreignId, morphs, or a plain nullable index. This determines your whole integration shape.
   • config/<package>.php — country list source, table names, model bindings, formatter options.
   • The Address model (or contract) and any HasAddress trait / addresses() relation.
   • The package README's address section, which the release notes assume you've read.

4. First use case. Attach an address to an existing model and render it:

   // on User, Order, etc.
   use Vendor\Package\Concerns\HasAddress;
   
   class Order extends Model
   {
       use HasAddress;
   }
   

   $order->address()->create([
       'line_1'   => '1 Main St',
       'city'     => 'Springfield',
       'postcode' => '12345',
       'country'  => 'US',
   ]);
   
   echo $order->address->formatted; // or the package's formatter helper
   

   Confirm the exact attribute names against the migration before writing this into your app — they are the contract you'll live with.

Implementation Patterns

Deployment sequence. Because v1.1.0 is migration-driven, wire it into your release pipeline in a fixed order: composer install → php artisan migrate --force → php artisan config:cache → queue:restart. Running config:cache before the migration is fine, but running it before publishing the config is not.

Treat the address as normalized data, not a blob. Store line_1/line_2, city, region, postcode, country (ISO 3166-1 alpha-2), and keep a derived formatted accessor for display. This keeps you able to filter by country/region later without a data migration.

Pick single vs. multiple addresses deliberately. If the package ships a polymorphic relation, you get "many addresses per model" for free — in that case add your own is_default boolean with a partial unique index, rather than assuming the package handles default selection:

$table->boolean('is_default')->default(false);
$table->unique(['addressable_type', 'addressable_id', 'is_default']);

(Adjust or drop for MySQL, which doesn't support partial indexes.)

Validate at the edge, not in the model. Use FormRequest validation for address input and keep the package's model as a plain persistence object. Country/region validation is best driven from the package's config/DB list rather than a hand-written in: rule.

Wrap it in an API Resource. Address columns will change between package versions more readily than your public JSON contract:

class AddressResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'line_1'   => $this->line_1,
            'city'     => $this->city,
            'postcode' => $this->postcode,
            'country'  => $this->country,
            'formatted'=> $this->formatted,
        ];
    }
}

Eager load when formatting. Formatted output often resolves country/region labels. On an index of 50 orders this is a classic N+1:

Order::with('address')->paginate();

Testing. Use RefreshDatabase so the new migration runs, and build addresses through a factory if the package ships one. If you test on SQLite in-memory, watch for MySQL-only column types in the migration (see gotchas).

Multi-tenant / soft deletes. If your models are soft-deleted, an address row can be orphaned. Either cascade on delete at the DB level or add the package's model to your pruning strategy. If the package doesn't support soft deletes on addresses, don't add the column yourself — it will fight the package's queries.

Gotchas and Tips

• The migration is the release. Upgrading the composer package without running php artisan migrate leaves you with a class that references a nonexistent table. Every "address information not working" report after this upgrade starts here.
• Migration ordering and morph keys. If the address table uses morphs('addressable'), the combined index on (addressable_type, addressable_id) can exceed the index length limit on older MySQL with utf8mb4. Check the generated migration and, if needed, set Schema::defaultStringLength(191) or a shorter morph key.
• Publish vs. re-publish. vendor:publish overwrites. On an existing install, publish with --force only for config after diffing it, and never re-publish a migration that has already run in production — it will be skipped or, worse, duplicated under a new timestamp.
• Config caching hides your edits. If address behaviour changes don't seem to apply, you're almost certainly looking at a cached config. php artisan config:clear before debugging.
• Country/region data goes stale. Packages that bundle ISO lists ship them as static data. Don't build compliance or shipping logic on an unverified list; check the package's data source and refresh path, and keep the country code canonical (alpha-2 vs. alpha-3 is a common mismatch).
• Don't assume the address attribute is an array. It may be cast to a DTO or value object. $model->address['city'] failing with "Cannot use object as array" is the usual symptom — check $casts and the accessor first.
• Postal code validation is jurisdiction-specific. If the package ships rules, they're likely conservative. Don't extend them with a single global regex; validate per-country or leave it permissive and normalize on save.
• SQLite in tests vs. MySQL in production. Column types, index lengths, and json support differ. If your CI runs SQLite, add one job against your production engine before trusting the migration.
• Extension points to look for: a config-swappable model/contract, a formatter or presenter class you can bind your own implementation to, custom validation rules, and a morph map registration. These are the seams that let you avoid forking the package when the address schema inevitably evolves.