dallgoot/yaml

Provides loader, dumper and an API for YAML content. Loader builds to equivalent data types in PHP 8.x

1.0.0.0 2024-10-18 13:58 UTC

Requires

• php: >=8.1
• ext-json: *
• ext-pcre: *
• ext-spl: *
• lib-pcre: *

Requires (Dev)

• ext-reflection: *
• phan/phan: *
• phpmetrics/phpmetrics: *
• phpunit/phpunit: *

Apache-2.0

• dallgoot

• yaml
• parser
• writer
• reader

README

PHP library to load and parse YAML file to coherent PHP datatypes equivalent

Installation

• Dependencies are only useful for building documentation or for code contribution, so the "--update-no-dev" prevent from downloading and managing packages that you probably won't use.

You first need Composer and PHP ^8.1.14

composer require --update-no-dev dallgoot/yaml

Usage

See examples folder

Features

• consistent PHP datatypes :
  • object for mappings
  • array for sequences
  • common scalars : string, integer, float, INF, NAN
  • JSON, DateTime(option), etc.
• specific types (objects)
  • YamlObject for each Yaml content (multi-documents YAML is an array of YamlObject)
  • Compact for compact/short YAML syntax
  • Tagged object when tag is not determinable
• recover from some parsing errors
• tolerant to tabulations
• debug levels :
  • 1 : print each line Node Type class and exit
  • 2 : print Loader global tree structure and exit
  • 3 : print each document NodeList and exit

Support

• YAML specifications version 1.2
• multi-line values (simple|double quoted or not, compact mapping|sequence or JSON)
• multiple documents in a content (file or string)
• compact syntax for mappings and sequences
• comments (not yet implemented)
• references (option : enabled by default)
• tags with behaviour customization (overriding for common(CoreSchema), or specifying for custom) via implementing Tag/SchemaInterface.

What's different from other PHP Yaml libraries ?

• coherent data types (see coherence.md for explanations)
• JSON format validation (Option, Note: if valid as per PHP function json_encode)
• complex mapping (Note: keys are JSON formatted strings)
• real reference behaviour : changing reference value modify other reference calls

Contributing

Only contributions concerning bug fixes will be review ATM. Requests for features will be dealt with after reading/writing YAML is considered bug free (and al current Options are implemented)

ToDo

• Code coverage : target 100%
• Benchmarks against other libs

Improvements

• Examples of each function of the API
• implement specific unit test for each YAML spec. invalid cases (what must not happen)
• DUMPER:
  • implement/verify Dumper::Options
• better/more precise errors identification (Yaml validation) with explanation in YAML content
• Unicode checking (???)
• OPTION : parse dates as PHP DateTime object
• OPTION: Force renaming key names that are not valid PHP property name
• TAG : function for 'php/object' that provides the correct namespace to build
• NEON compatibility???
• make immutable YamlObject

Performances

- TBD
- improved memory using SplFixedArray instead of regular arrays where possible

Sponsor

That is greatly appreciated :

Thanks

• https://yaml.org
• https://www.json2yaml.com/convert-yaml-to-json
• Symfony Yaml