Squire

<p align="center"> <img src="https://user-images.githubusercontent.com/41773797/104140339-f54ce300-53a8-11eb-8049-8d0994a6cd36.png" alt="Package banner" style="width: 100%; max-width: 800px;" /> </p> <p align="center"> <a href="https://github.com/squirephp/squire/actions"><img alt="Tests passing" src="https://img.shields.io/badge/Tests-passing-green?style=for-the-badge&logo=github"></a> <a href="https://laravel.com"><img alt="Laravel v8.x" src="https://img.shields.io/badge/Laravel-v8.x-FF2D20?style=for-the-badge&logo=laravel"></a> <a href="https://php.net"><img alt="PHP 8" src="https://img.shields.io/badge/PHP-8-777BB4?style=for-the-badge&logo=php"></a> </p>

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 based on the concepts 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.
• Validating user input.

Contents

• Installing a Model
• Using a Model
• Available Models
  • Squire\Models\Airline
  • Squire\Models\Airport
  • Squire\Models\Continent
  • Squire\Models\Country
  • Squire\Models\Currency
    • Formatting money
  • Squire\Models\GbCounty
  • Squire\Models\Region
  • Squire\Models\Timezone
• Model Relationships
• Validation
• Creating your own Models
• Adding a localization
• Upgrading from 1.x
• Need Help?

Installing a Model

You can use Composer to install Squire models into your application. Each model is available in a variety of languages, and you need only install the ones you will use.

As an example, you can install the Squire\Models\Country model in English:

composer require squirephp/countries-en

A complete list of available models is below.

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

Installation

| Locale | Installation Command | |--|--| | English | composer require squirephp/airlines-en |

Schema

| 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 |

Relationships

| Relationship name | Model | |--|--| | country | Squire\Models\Country | | continent | Squire\Models\Continent |

Squire\Models\Airport

Installation

| Locale | Installation Command | |--|--| | English | composer require squirephp/airports-en |

Schema

| Column Name | Description | Example | |--|--|--| | code_iata | IATA code of the airport. | lhr | | code_icao | ICAO code of the airport. |egll | | country_id | ISO 3166-1 alpha-2 country code of the airport. | gb | | municipality | Municipality of the airport. | London | | name | Name of the airport. | London Heathrow Airport | | timezone_id | PHP timezone identifier of the airport. | Europe/London |

Relationships

| Relationship name | Model | |--|--| | country | Squire\Models\Country | | timezone | Squire\Models\Timezone |

Squire\Models\Continent

Installation

| Locale | Installation Command | | ------- | -------------------------------------------------- | | German | composer require squirephp/continents-de | | English | composer require squirephp/continents-en | | Polish | composer require squirephp/continents-pl | | Italian | composer require squirephp-italian/continents-it |

Schema

| Column Name | Description | Example | |--|--|--| | code | Two letter continent code. | na | | name | Continent name. | North America |

Relationships

| Relationship name | Model | |--|--| | countries | Squire\Models\Country | | regions | Squire\Models\Region | | timezones | Squire\Models\Timezone |

Squire\Models\Country

Installation

| Locale | Installation Command | | ------- | ------------------------------------------------------- | | English | composer require squirephp/countries-en | | French | composer require squirephp/countries-fr | | German | composer require squirephp/countries-de | | Polish | composer require squirephp/countries-pl | | Spanish | composer require squirephp/countries-es | | Dutch | composer require quickstreambe/squirephp-countries-nl | | Italian | composer require squirephp-italian/countries-it |

Schema

| 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 |

Relationships

| Relationship name | Model | |--|--| | airlines | Squire\Models\Airline | | airports | Squire\Models\Airport | | continent | Squire\Models\Continent | | currency | Squire\Models\Currency | | regions | Squire\Models\Region | | timezones | Squire\Models\Timezone |

Squire\Models\Currency

Installation

| Locale | Installation Command | |--|--| | English | composer require squirephp/currencies-en |

Schema

| 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. | $ |

Relationships

| Relationship name | Model | |--|--| | countries | Squire\Models\Country |

Formatting money

You may use the format() method on any currency model instance to format a given number in that currency:

Currency::find('usd')->format(500) // $5.00
Currency::find('usd')->format(500, true) // $500.00, converted

This functionality uses akaunting/laravel-money internally.

Squire\Models\GbCounty

Installation

| Locale | Installation Command | |--|--| | English | composer require squirephp/gb-counties-en |

Schema

| 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 |

Relationships

| Relationship name | Model | |--|--| | region | Squire\Models\Region |

Squire\Models\Region

Installation

| Locale | Installation Command | |--|--| | English | composer require squirephp/regions-en |

Schema

| 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 |

Relationships

| Relationship name | Model | |--|--| | continent | Squire\Models\Continent | | country | [`Squi