danharrin / squire
A library of static Eloquent models for common fixture data.
Fund package maintenance!
danharrin
Requires
- php: ^7.2|^8.0
- calebporzio/sushi: ^2.1
- illuminate/database: ^6.0 || ^7.0 || ^8.0
Requires (Dev)
- orchestra/testbench: ^6.2
- phpunit/phpunit: ^9.4
This package is auto-updated.
Last update: 2021-05-07 11:22:52 UTC
README
NOTICE: This v1.x package has been deprecated in favour of v2.x and is no longer maintained. Learn more.
Squire is a library of static Eloquent models for fixture data that is commonly needed in web applications, such as countries, currencies and airports. It's built on top of Caleb Porzio's Sushi package.
Common use cases for Squire include:
- Populating dropdown options, such as a country selector on an address form.
- Attaching extra data to other models in your app, such as airport information to a
Flight
model. See the section on model relationships.
Contents
- Installing Squire
- Using a model
- Available models
- Model relationships
- Column customisation
- Contributing
Installing Squire
You can use Composer to install Squire into your application.
composer require danharrin/squire
No additional setup is required.
Using a model
You can interact with a Squire model just like you would any other Eloquent model, except that it only handles read-only operations.
use Squire\Models\Country; Country::all(); // Get information about all countries. Country::find('us'); // Get information about the United States. Country::where('name', 'like', 'a%')->get(); // Get information about all countries beginning with the letter "a".
Available models
Squire\Models\Airline
Column Name | Description | Example |
---|---|---|
alias |
Alternative name of the airline. | EasyJet Airline |
call_sign |
Call sign of the airline. | EASY |
code_iata |
IATA code of the airline. | u2 |
code_icao |
ICAO code of the airline. | ezy |
country_id |
ISO 3166-1 alpha-2 country code of the airline. | gb |
name |
Name of the airline. | easyJet |
Relationship name | Model |
---|---|
country |
Squire\Models\Country |
continent |
Squire\Models\Continent |
Squire\Models\Airport
Column Name | Description | Example |
---|---|---|
code_gps |
GPS code of the airport. | ayse |
code_iata |
IATA code of the airport. | nis |
code_icao |
Local code of the airport. | sbi |
municipality |
Municipality of the airport. | Simberi Island |
name |
Name of the airport. | Simberi Airport |
region_id |
ISO 3166-2 region code of the airport. | pg-nik |
type |
Type of airport. | small_airport |
Relationship name | Model |
---|---|
country |
Squire\Models\Country |
region |
Squire\Models\Region |
Squire\Models\Continent
Column Name | Description | Example |
---|---|---|
code |
Two letter continent code. | na |
name |
Continent name. | North America |
Relationship name | Model |
---|---|
countries |
Squire\Models\Country |
regions |
Squire\Models\Region |
Squire\Models\Counties\GbCounty
Column Name | Description | Example |
---|---|---|
code |
ISO 3166-2 county code. | gb-ess |
name |
County name. | Essex |
region_id |
ISO 3166-2 region code of the county. | gb-eng |
Relationship name | Model |
---|---|
region |
Squire\Models\Region |
Squire\Models\Country
Column Name | Description | Example |
---|---|---|
calling_code |
E.164 country calling code. | 1 |
capital_city |
Capital city of the country. | Washington |
code_2 |
ISO 3166-1 alpha-2 country code. | us |
code_3 |
ISO 3166-1 alpha-3 country code. | usa |
continent_id |
Two letter continent code of the country. | na |
currency_id |
ISO 4217 alphabetic currency code of the country. | usd |
flag |
Unicode flag of the country. | 🇺🇸 |
name |
Country name. | United States |
Relationship name | Model |
---|---|
airlines |
Squire\Models\Airline |
airports |
Squire\Models\Airport |
continent |
Squire\Models\Continent |
currency |
Squire\Models\Currency |
regions |
Squire\Models\Region |
Squire\Models\Currency
Column Name | Description | Example |
---|---|---|
code_alphabetic |
ISO 4217 alphabetic currency code. | usd |
code_numeric |
ISO 4217 numeric currency code. | 840 |
decimal_digits |
Number of decimal digits to use when formatting this currency. | 2 |
name |
Currency name. | US Dollar |
name_plural |
Plural currency name. | US Dollars |
rounding |
The formatting precison of this currency. | 0 |
symbol |
International currency symbol. | $ |
symbol_native |
Native currency symbol. | $ |
Relationship name | Model |
---|---|
countries |
Squire\Models\Country |
Squire\Models\Region
Column Name | Description | Example |
---|---|---|
code |
ISO 3166-2 region code. | us-ny |
country_id |
ISO 3166-1 alpha-2 country code. | us |
name |
Region name. | New York |
Relationship name | Model |
---|---|
airports |
Squire\Models\Airport |
continent |
Squire\Models\Continent |
country |
Squire\Models\Country |
gbCounties |
Squire\Models\County\GbCounty |
Model relationships
Implementing an Eloquent relationship between a model in your app and a Squire model is very simple. There are a couple of approaches you could take.
Using inheritance
The simplest option is to create a new model in your app, and let it extend the Squire model. Your new app model will now behave like the original Squire model, except you can register new methods and customise it to your liking:
<?php namespace App\Models; use Squire\Models\Country as SquireCountry; class Country extends SquireCountry { public function users() { return $this->hasMany(User::class); } }
See our section on model customisation for more customisation possibilities that are made available if you utilise this method.
Using resolveRelationUsing()
Another option is the resolveRelationUsing()
method. This allows you to dynamically register a relationship for a Squire model from anywhere in your app, for example, within a service provider:
use App\Models\User; use Squire\Models\Country; Country::resolveRelationUsing('users', function (Country $country) { return $country->hasMany(User::class); });
Column customisation
Squire allows you to customise the column names on any provided model.
Create a new model within your app and let it extend the Squire model that you would like to customise:
<?php namespace App\Models; use Squire\Models\Country as SquireCountry; class Country extends SquireCountry { protected $map = [ 'dial_code' => 'calling_code', ]; }
In this example, the App\Models\Country
, extending the Squire\Models\Country
model, has the calling_code
column remapped to dial_code
:
use App\Models\Country; Country::find('us')->dial_code; // 1
Contributing
If you have fixture data to contribute to the library, please open a pull request!
For reference, check out the existing models.