Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sigwinhq/xezilaires-dev
Iterate structured Excel spreadsheets, normalize rows into value objects, validate, serialize into CSV, JSON, XML.
https://github.com/sigwinhq/xezilaires-dev
csv-export hacktoberfest iterator json-export normalization php php-tools serializable-objects serialization spreadsheet spreadsheet-data spreadsheet-mapper spreadsheets validation xml-export
Last synced: about 1 month ago
JSON representation
Iterate structured Excel spreadsheets, normalize rows into value objects, validate, serialize into CSV, JSON, XML.
- Host: GitHub
- URL: https://github.com/sigwinhq/xezilaires-dev
- Owner: sigwinhq
- License: mit
- Created: 2018-07-17T16:16:22.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-06-24T14:53:05.000Z (7 months ago)
- Last Synced: 2024-12-16T10:23:00.729Z (about 1 month ago)
- Topics: csv-export, hacktoberfest, iterator, json-export, normalization, php, php-tools, serializable-objects, serialization, spreadsheet, spreadsheet-data, spreadsheet-mapper, spreadsheets, validation, xml-export
- Language: PHP
- Homepage:
- Size: 472 KB
- Stars: 61
- Watchers: 4
- Forks: 4
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Xezilaires
Xezilaires is a PHP library which helps to iterate structured Excel spreadsheets,
normalize rows into value objects, validate, serialize into CSV, JSON, XML.
[](https://github.com/sigwinhq/xezilaires-dev)
[](https://github.com/sigwinhq/xezilaires-dev/actions)
[](https://github.com/phpstan/phpstan)
[](https://github.com/vimeo/psalm)
## What it does
1. we create a PHP class which will hold our Excel row data
2. we next create spreadsheet iterator instance
1. passing the path to the Excel file we wish to read
2. passing the configuration mapping the Excel columns into PHP properties
3. as we're iterating, we are getting an value object (instance of the defined class)
for each row
Think of it as an "ORM" *(Object Relation Manager)* for an Excel file.
An OEM *(Object Excel Manager)*, if you will.
## Example usage
### Without attributes
```php
class Product
{
private $name;
}
$symfonySerializer = new \Symfony\Component\Serializer\Serializer([
new \Symfony\Component\Serializer\Normalizer\PropertyNormalizer(),
]);
$normalizer = new \Xezilaires\Bridge\Symfony\Serializer\ObjectSerializer($symfonySerializer);
$iteratorFactory = new \Xezilaires\SpreadsheetIteratorFactory($normalizer, [
\Xezilaires\Bridge\PhpSpreadsheet\Spreadsheet::class,
]);
$iterator = $iteratorFactory->fromFile(
// https://github.com/sigwinhq/xezilaires-dev/raw/master/src/Xezilaires/Test/resources/fixtures/products.xlsx
new \SplFileObject(__DIR__.'/../../src/Xezilaires/Test/resources/fixtures/products.xlsx'),
new \Xezilaires\Metadata\Mapping(
Model\Product::class,
[
'name' => new \Xezilaires\Metadata\ColumnReference('A'),
],
[
// options
'start' => 2,
]
)
);
```
### With attributes
```php
use Xezilaires\Attribute as XLS;
#[XLS\Options(header=1, start=2)]
class Product
{
#[@XLS\HeaderReference(header="Name")]
private $name;
}
$symfonySerializer = new \Symfony\Component\Serializer\Serializer([
new \Symfony\Component\Serializer\Normalizer\PropertyNormalizer(),
]);
$normalizer = new \Xezilaires\Bridge\Symfony\Serializer\ObjectSerializer($symfonySerializer);
$iteratorFactory = new \Xezilaires\SpreadsheetIteratorFactory($normalizer, [
\Xezilaires\Bridge\PhpSpreadsheet\Spreadsheet::class,
]);
$attributeDriver = new \Xezilaires\Metadata\Attribute\AttributeDriver();
$iterator = $iteratorFactory->fromFile(
// https://github.com/sigwinhq/xezilaires-dev/raw/master/src/Xezilaires/Test/resources/fixtures/products.xlsx
new \SplFileObject(__DIR__.'/../../src/Xezilaires/Test/resources/fixtures/products.xlsx'),
$attributeDriver->getMetadataMapping(Product::class, ['reverse' => true])
);
```
See more examples in the [`docs/examples/`](./docs/examples/) folder.
## Options
- `start`, which row do we start on
*(integer, optional, default: `1`)*
- `header`, which row contains the header labels
*(integer, optional if not using `HeaderReference`, default: `null`)*
- `reverse`, do we iterate the rows in reverse, from end to start
*(boolean, optional, default: `false`)*
- `sequential`, is the key sequential (0, 1, 2) or represents current row?
*(boolean, optional, default: `false`)*
## Features
Features included:
- **Reading Excel files**
*(using either `phpoffice/PhpSpreadsheet` or `openspout/openspout`)*
- **Denormalization / normalization** support
*(using `symfony/serializer`, from / to all supported formats)*
- Attributes support
- mapping via **column names** or **header labels**
*(saying "Map header label `PrdctEN` to property `product`")*
- **A Symfony bundle**
*(for easy integration into existing apps)*
- CLI *(command-line interface)* tool
## Custom normalizers / validators
You can use your own normalizers / validators by passing your own Symfony bundle
which registers them to the Xezilaires commands via `--bundle`, like so:
```
vendor/bin/xezilaires validate --bundle Xezilaires\\Test\\ExampleBundle\\XezilairesExampleBundle Xezilaires\\Test\\Model\\Product src/Xezilaires/Test/resources/fixtures/products.xlsx
```
See example bundle in [`src/Xezilaires/Test/ExampleBundle/`](./src/Xezilaires/Test/ExampleBundle/).
## What's with the name
`xezilaires` is `serializex` backwards.
We added the X so the name so we can shorten it as [XLS](https://fileinfo.com/extension/xls).
As a side-effect, we [made reading Excel files with this library cool](https://tvtropes.org/pmwiki/pmwiki.php/Main/XMakesAnythingCool).