Documentation Ideas

[rotexdegba]

• Specify \LeanOrm\Model specific methods not present in \GDAO\Model in the documentation

• Because Collection::getModel(), Record::getModel() & ReadOnlyRecord::getModel() all return \GDAO\Model, you will most likely not get IDE auto-completion for \LeanOrm\Model specific methods when you call getModel() & try to call Model methods on the return value. To fix this you can create base Collection & Record classes that extend the Collection & Record classes & redefine getModel() in those base classes to return \LeanOrm\Model. Then you can make all the Collection & Record classes in your application extend those base classes or you could use those base classes directly with your Model objects. Overrode getModel() in the record & collection classes generated by leanorm-cli to return the corresponding model class.

• Update class diagrams with only public methods

• Collection->loadData(\GDAO\Model\RecordInterface ...$data_2_load) totally replaces all items in a collection. To append records to a Collection use the $collection[$key] = $record syntax. Put a warning about this in the docs.

• You can create Records & Collections either via their constructor or by calling createNewRecord & createNewCollection on a model instance

• You can add records created by different Model Class instances to the same collection. This should be avoided though, because it may lead to unpredictable behavior when calling collection methods like deleteAll & saveAll

• Document how to debug queries:

How to debug:

// start debugging
$model->enableQueryLogging()->setLogger($psrLogger);
// some calls to $model methods
//......
//.....
// Finish debugging
$model->disableQueryLogging();
// you can check the log destination you specified for your $psrLogger 
// to see all the under the hood queries or you could do a dump of
// \LeanOrm\Model::getQueryLogForAllInstances() to see all Queries 
// for $model & all instances of Model that were created in the code 
// you are debugging above,
// or \LeanOrm\Model::getQueryLogForAllInstances($model) to see
// all Queries for $model only in the code you are debugging above.

• Remember to add to the documentation that only one pdo object gets created for each unique dsn, which means that all instances of \LeanOrm\Model and its sub-classes that are created using the same dsn string, will share one single pdo object under the hood. This is very helpful for sqlite when multiple Models with the same dsn try to write to the same sqlite file, they will all be using only one pdo connection to write to that sqlite database file. Sqlite does not support concurrency, so having an instance of a pdo connection per Model class, whether or not their dsn's are the same or different will mean that only the first instance to connect to the sqlite file will have both read and write access, the remaining instances will only be able to successfully read. Other databases like Mysql, do not have this issue and would work well if there are either one pdo instance shared among multiple Model instances with the same dsn or one pdo instance per Model instance (regardless of whether they have the same or different dsn).

• Document that insert only allows values that are either of type string, null, boolean, numeric or Stringable objects. Any values that are not in this range will lead to a \GDAO\ModelInvalidInsertValueSuppliedException being thrown during insert.

• Add examples of how to implement validation using a 3rd party library like AuraFilter. Not adding filtering and validation in order to give consumers flexibility on how this should happen.

• Add documentation on how to use Versatile Collections to turbo charge arrays of records particularly with the SpecificObjectsCollection to enable things like invoking methods on all records in a collection by calling the method once on the collection object. The records can be loaded back into a new instance of \LeanOrm\Model\Collection for bulk DB operations like saveAll or deleteAll

• Provide extensive Query building examples with Aura Sql Query https://github.com/auraphp/Aura.SqlQuery/tree/2.8.0 . Revamp Query Building #3

• Look into switching to using plain old markdown files or continuing documentation via http://rotexsoft.github.io/leanorm/ or some other solution like MKDocs or readthedocs [ON PAUSE]

• Update documentation for fetch method to reflect change that allows the use of scalars

• Query Logging #16

• Create a cli package for generating classes #17

• add instructions on how to create the test blog database and populate it with data so that users reading the documentation can follow along. The dB should be an sqlite one so that users don't have to worry about setting up postgres, mysql etc