tableschema-php
, (*1)
A utility library for working with Table Schema in PHP., (*2)
Features summary and Usage guide
Installation
$ composer require frictionlessdata/tableschema
Table
Table class allows to iterate over data conforming to a table schema, (*3)
Instantiate a Table object based on a data source and a table schema., (*4)
use frictionlessdata\tableschema\Table;
$table = new Table("tests/fixtures/data.csv", ["fields" => [
["name" => "first_name"],
["name" => "last_name"],
["name" => "order"]
]]);
Schema can be any parameter valid for the Schema object (See below), so you can use a url or filename which contains the schema, (*5)
$table = new Table("tests/fixtures/data.csv", "tests/fixtures/data.json");
iterate over the data, all the values are cast and validated according to the schema, (*6)
foreach ($table as $row) {
print($row["order"]." ".$row["first_name"]." ".$row["last_name"]."\n");
};
validate function will validate the schema and get some sample of the data itself to validate it as well, (*7)
Table::validate(new CsvDataSource("http://invalid.data.source/"), $schema);
You can instantiate a table object without schema, in this case the schema will be inferred automatically based on the data, (*8)
$table = new Table("tests/fixtures/data.csv");
$table->schema()->fields(); // ["first_name" => StringField, "last_name" => StringField, "order" => IntegerField]
Optionally, specify a CSV Dialect:, (*9)
$table = new Table("tests/fixtures/data.csv", null, ["delimiter" => ";"]);
Table::read method allows to get all data as an array, it also supports options to modify reader behavior, (*10)
$table->read() // returns all the data as an array
read accepts an options parameter, for example:, (*11)
$table->read(["cast" => false, "limit": 5])
The following options are available (the values are the default values):, (*12)
$table->read([
"keyed" => true, // flag to emit keyed rows
"extended" => false, // flag to emit extended rows
"cast" => true, //flag to disable data casting if false
"limit" => null, // integer limit of rows to return
]);
Additional methods and functionality, (*13)
$table->headers() // ["first_name", "last_name", "order"]
$table->save("output.csv") // iterate over all the rows and save the to a csv file
$table->schema() // get the Schema object
$table->read() // returns all the data as an array
Schema
Schema class provides helpful methods for working with a table schema and related data., (*14)
use frictionlessdata\tableschema\Schema;, (*15)
Schema objects can be constructed using any of the following:, (*16)
$schema = new Schema([
'fields' => [
[
'name' => 'id', 'title' => 'Identifier', 'type' => 'integer',
'constraints' => [
"required" => true,
"minimum" => 1,
"maximum" => 500
]
],
['name' => 'name', 'title' => 'Name', 'type' => 'string'],
],
'primaryKey' => 'id'
]);
$schema = new Schema("{
\"fields\": [
{\"name\": \"id\"},
{\"name\": \"height\", \"type\": \"integer\"}
]
}");
$schema = new Schema("https://raw.githubusercontent.com/frictionlessdata/testsuite-extended/ecf1b2504332852cca1351657279901eca6fdbb5/datasets/synthetic/schema.json");
The schema is loaded, parsed and validated and will raise exceptions in case of any problems., (*17)
access the schema data, which is ensured to conform to the specs., (*18)
$schema->missingValues(); // [""]
$schema->primaryKey(); // ["id"]
$schema->foreignKeys(); // []
$schema->fields(); // ["id" => IntegerField, "name" => StringField]
$field = $schema->field("id"); // Field object (See Field reference below)
validate function accepts the same arguemnts as the Schema constructor but returns a list of errors instead of raising exceptions, (*19)
// validate functions accepts the same arguments as the Schema constructor
$validationErrors = Schema::validate("http://invalid.schema.json");
foreach ($validationErrors as $validationError) {
print(validationError->getMessage();
};
validate and cast a row of data according to the schema, (*20)
$row = $schema->castRow(["id" => "1", "name" => "First Name"]);
will raise exception if row fails validation, (*21)
it returns the row with all native values, (*22)
$row // ["id" => 1, "name" => "First Name"];
validate the row to get a list of errors, (*23)
$schema->validateRow(["id" => "foobar"]); // ["id is not numeric", "name is required" .. ]
Infer schema based on source data:, (*24)
$schema = Schema::infer("tests/fixtures/data.csv");
$table->schema()->fields(); // ["first_name" => StringField, "last_name" => StringField, "order" => IntegerField]
You can also create a new empty schema for editing, (*25)
$schema = new Schema();
set fields, (*26)
$schema->fields([
"id" => (object)["type" => "integer"],
"name" => (object)["type" => "string"],
]);
appropriate Field object is created according to the given descriptor (see below for Field class reference), (*27)
$schema->field("id"); // IntegerField object
add / update or remove fields, (*28)
$schema->field("email", ["type" => "string", "format" => "email"]);
$schema->field("name", ["type" => "string"]);
$schema->removeField("name");
set or update other table schema attributes, (*29)
$schema->primaryKey(["id"]);
after every change - schema is validated and will raise Exception in case of validation errors, (*30)
Finally, you can get the full validated descriptor, (*31)
$schema->fullDescriptor();
And, save it to a json file, (*32)
$schema->save("my-schema.json");
Field
Field class represents a single table schema field descriptor, (*33)
Create a field from a descriptor, (*34)
use frictionlessdata\tableschema\Fields\FieldsFactory;
$field = FieldsFactory::field([
"name" => "id", "type" => "integer",
"constraints" => ["required" => true, "minimum" => 5]
]);
Cast and validate values using the field, (*35)
$field->castValue("3"); // exception: value is below minimum
$field->castValue("7"); // 7
Additional method to access field data, (*36)
$field("id")->format(); // "default"
$field("id")->name(); // "id"
$field("id")->type(); // "integer"
$field("id")->constraints(); // (object)["required"=>true, "minimum"=>1, "maximum"=>500]
$field("id")->enum(); // []
$field("id")->required(); // true
$field("id")->unique(); // false
$field("id")->title(); // "Id" (or null if not provided in descriptor)
$field("id")->description(); // "The ID" (or null if not provided in descriptor)
$field("id")->rdfType(); // "http://schema.org/Thing" (or null if not provided in descriptor)
Contributing
Please read the contribution guidelines: How to Contribute, (*37)
Wallogit.com
