Need help with squire?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

squirephp
412 Stars 19 Forks MIT License 77 Commits 0 Opened issues

Description

A library of static Eloquent models for common fixture data.

Services available

!
?

Need anything else?

Contributors list

Package banner

Tests passing Laravel v8.x PHP 8

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

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

Relationships

| Relationship name | Model | |--|--| |

country
|
Squire\Models\Country
| |
region
|
Squire\Models\Region
|

Squire\Models\Continent

Installation

| Locale | Installation Command | |--|--| | English |

composer require squirephp/continents-en
|

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
|

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
| | Spanish |
composer require squirephp/countries-es
|

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
|

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
|

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

airports
|
Squire\Models\Airport
| |
continent
|
Squire\Models\Continent
| |
country
|
Squire\Models\Country
| |
gbCounties
|
Squire\Models\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:

use Squire\Models\Country as SquireCountry;

class Country extends SquireCountry { public function users() { return $this->hasMany(User::class); } }

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); });

Validation

Squire includes a validation rule for each model installed in your app. These allow you to easily validate user input to ensure that it matches a record in a specific model.

Rules can be found in the

Squire\Rules
namespace. To use one, simply construct a new rule class and pass in the model column name that you would like to validate against:
use Squire\Rules;

$request->validate([ 'country' => ['required', 'string', new Rules\Country('name')], ]);

This code will validate the

country
input against the
name
column on the
Squire\Models\Country
model
. If the user enters a country that does not exist, a validation error will be thrown.

Creating your own Models

Squire may not always have a model available for the information you require. In this case, you may want to create your own.

Creating a Model

Squire models are very simple classes that extend

Squire\Model
. Install it with:
composer require squirephp/model

Your model class should contain a single static property,

$schema
. This contains the column structure for your model, and should match the format of the source data.
use Squire\Model;

class Language extends Model { public static $schema = [ 'id' => 'string', 'name' => 'string', ]; }

Attaching a Model Source

Your model will require at least one data source to be registered. Each registered data source is associated with a locale. To register a data source, you will need to interact with

Squire\Repository
. Install it with:
composer require squirephp/repository

Inside a service provider, register an English source for your model:

use App\Models\Language;
use Illuminate\Support\ServiceProvider;
use Squire\Repository;

class ModelServiceProvider extends ServiceProvider { public function boot() { Repository::registerSource(Language::class, 'en', DIR.'/../../resources/squire-data/languages-en.csv'); } }

In this example, the

/resources/squire-data/languages-en.csv
file should be present in your app, and contain the English data served to the model. The column structure should match the
$schema
defined in your model:
id,name
de,German
en,English
fr,French
es,Spanish

Creating a Validation Rule

Rules allow you to validate user input to ensure that it matches a record in a specific model. Rule classes extend

Squire\Rule
. Install it with:
composer require squirephp/rule

Your rule class should contain, at minimum, a

$message
to be served if the validation fails, and a
getQueryBuilder()
method for your model.
use App\Models;
use Squire\Rule;

class Language extends Rule { protected $message = 'validation.language';

protected function getQueryBuilder()
{
    return Models\Language::query();
}

}

If no column is passed to your rule when it's used,

id
will be used by default. To customise this, override the
$column
property on your rule:
use Squire\Rule;

class Language extends Rule { protected $column = 'name'; }

Releasing a Model

Squire models, their sources, and validation rules are all simply releasable in Composer packages. To see an example of this in action, check out the

squirephp/countries
and
squirephp/countries-en
packages.

Upgrading from 1.x

First, you must remove the 1.x package with Composer:

composer remove danharrin/squire

Next, assess which models you are currently using in your application. Install them using the individual command listed for each. If your app requires localisation features offered by Squire, you may install more than one translation of each model.

As an example, we will install the

Squire\Models\Country
and
Squire\Models\Continent
models in English:
composer require squirephp/countries-en squirephp/continents-en

Breaking Changes Introduced in 2.x

  • The original

    Squire\Models\Counties\GbCounty
    model has now been moved to
    Squire\Models\GbCounty
    .
  • The

    $map
    property has been deprecated to improve performance of the package with large datasets. Please set up Eloquent accessors if you require a similar feature.

Need Help?

🐞 If you spot a bug with this package, please submit a detailed issue, and wait for assistance.

🤔 If you have a question or feature request, please start a new discussion.

🔐 If you discover a vulnerability within the package, please review our security policy.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.