php-dataset/README.md

83 lines
2.5 KiB
Markdown
Raw Permalink Normal View History

2022-09-03 00:28:03 +00:00
# Dataset Library for PHP/Composer
2022-10-30 22:21:53 +00:00
This is a library for loading datasets from bundled packages. The idea isn't to
use the classes in this library as a generic datasource, although you could
probably pull that off. Instead, use the datasets to import the relevant data to
your database of choice, and optionally keep track of the version numbers so
new data can be imported automatically when the dependencies have been updated
and a new version has been installed.
2022-09-03 00:28:03 +00:00
2022-10-30 22:21:53 +00:00
## Installing
To install dataset, require it using composer:
2022-09-03 00:28:03 +00:00
2022-10-30 22:21:53 +00:00
```shell
$ composer require noccylabs/dataset
```
2022-09-03 00:28:03 +00:00
2022-10-30 22:21:53 +00:00
You also need some actual datasets. Some interesting ones could be:
Package | Description
---|---
[noccylabs/dataset-postal](https://dev.noccylabs.info/noccy/dataset-postal) | Patterns and info for postal (zip) code validation
[noccylabs/dataset-calendar](https://dev.noccylabs.info/noccy/dataset-calendar) | Bank holidays
[noccylabs/dataset-iso3166](https://dev.noccylabs.info/noccy/dataset-iso3166) | ISO 3166 country codes and namess
## Example
2022-09-03 00:28:03 +00:00
```php
use NoccyLabs\Dataset\DatasetManager;
$dm = new DatasetManager();
2022-10-30 22:24:27 +00:00
// Call on getDataset() if you want access to the metadata,
// Replace with openDataset() to quicly call getDataset()->open()
2022-10-30 22:21:53 +00:00
$ds = $dm->getDataset("noccylabs/dataset-iso3166#countries");
2022-10-30 22:24:27 +00:00
// This is how you get the metadata
2022-10-30 22:21:53 +00:00
echo "Dataset ID: ".$ds->getIdentifier(); // noccylabs/dataset-iso3166#countries
echo "Dataset version: ".$ds->getVersion(); // 2022.10.1
2022-09-03 00:28:03 +00:00
2022-10-30 22:21:53 +00:00
// Get a reader by calling open()
$reader = $ds->open();
foreach ($reader as $row) {
2022-09-03 14:23:46 +00:00
// row is an array
2022-09-03 00:28:03 +00:00
}
```
# Documentation
## DatasetManager
The `DatasetManager` will automatically locate and load datasets on startup.
```
getDataset(string $identifier): Dataset
Return a Dataset object, or throw exception on error
openDataset(string $identifer): Iterator
Return a reader for a Dataset, same as getDataset()->open()
getAvailableDatasets(): array
Returns the Dataset objects for all datasets found
```
## Dataset
```
open(): Iterator
Return an iterator to iterate over the data
filter(array|callable $condition): Iterator
Return an iterator that only returns rows matching filter
getIdentifier(): string
Return the dataset identifier (vendor/package#dataset)
getVersion(): string
Return the package version of the dataset
getPackageName(): string
Return the package name (vendor/package)
getDatasetName(): string
Return the dataset name (dataset)
getLicense(): ?string
Return the license for the dataset
getComment(): ?string
Return the dataset comment
```