earthit/storage

2.0.1 2024-01-05 18:08 UTC

README

Build Status

PHP Storage

A data access layer.

Goals:

  • Glean schema information from a EarthIT_Schema object.

  • Provide a consistent API for fetching from and storing into a database or databases.

  • Objects passed in and out are in 'schema form'; transformations to database form are done by the storage layer.

  • Allow custom storage layers to do additional transformations.

Design principles:

  • Excplicitly state which representations of objects are used where, rather than relying on coincidental similarities between them.

    • e.g. a function that takes an object should indicate in its documentation which form that object should be in.
  • Data is separate from the plumbing. Data objects are just arrays (or, conceivably, scalar values. But usually arrays).

  • Backend agnostic. May be RDB. May be something else entirely.

  • Allow efficient access to collections of objects of the same type.

    • Functions should generally be written to operate on collections to amortize overhead costs.
  • Should be able to use query generation and object conversion utilities independently.

  • Punting on multi-table joins for now. Easier to just do the joins in PHP by querying by sets of IDs, especially when links cross database boundaries.

Object representations

  • DB-internal form: actual bits stored in the database. Our PHP code never sees these.

  • DB-external form:

    Values from the database with minimal transformations applied to make them representable in PHP. e.g.

    • BIGINTs are represented as strings
    • GEOMETRY values are represented as GeoJSON strings

    Keys correspond exactly to column names.

  • Schema form: form as described in schema.txt.

    JSON fields are decoded

    keys are 'plain english' field names.

  • JSO form:

    Standard form for JSON REST services. Values will usually be the same as those in schema form, but keys will be 'camelCase' instead of 'plain english'.

    • "JSO" is not a typo. Objects in this form are the objects that would be JSON-encoded without JSON encoding yet applied, hence no 'N'.
    • 'id' field is added to objects that have composite keys.
    • Transforming to/from this form is out of the scope of this library.