Merge pull request #6 from tattersoftware/develop

Update for release

Author: MGatner

.github/workflows/codeigniter4-module.yml

@@ -0,0 +1,30 @@
+name: CodeIgniter4 ModuleTests
+
+on:
+  push:
+    branches: 
+      - develop
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@master
+      with:
+        php-version: '7.2'
+        extension-csv: intl, json, mbstring, mysqlnd, xdebug, xml
+        coverage: xdebug
+
+    - name: Validate composer.json
+      run: composer validate
+
+    - name: Install dependencies
+      run: composer install --prefer-dist --no-progress --no-suggest
+
+    - name: Run test suite
+      run: composer run-script test

README.md

@@ -42,7 +42,12 @@ in the comments. If no config file is found in **app/Config** the library will u
 * *Publish*: (not yet available) Modifies environments to match schema specs
 
 The **Schemas** service is also available to simplify a workflow with convenient wrapper functions.
+At its most basic (with automation enabled), the service will draft, archive, and return
+a schema with one simple command:
 
+	$schema = service('schemas')->get();
+
+You may want to control when portions of the workflow take place to optimize performance.
 Here is an example of one common process, mapping the default database group and storing
 the resulting schema to the cache:
 
@@ -55,7 +60,7 @@ $schemas->draft('database')->archive('cache');
 $schema = $schemas->read('cache')->draft('model')->get();
 ```
 
-If you need to deviate from the default configuration you can inject the handlers yourself:
+If you need to deviate from default handler configurations you can inject the handlers yourself:
 ```
 $db = db_connect('alternate_database');
 $databaseHandler = new \Tatter\Schemas\Drafter\Handlers\DatabaseHandler(null, $db);
@@ -72,7 +77,16 @@ Use the command to test and troubleshoot, or add it to your cron for periodic sc
 
 	php spark schemas -draft database,model -archive cache
 
-## Autodetection
+## Automation
+
+By default automation is turned on, but this can be configured via the `$automate` toggles
+in your config file. Automation will allow the service to fall back on a Reader, or even on
+a Drafter should it fail to have a schema already loaded. While automation makes using the
+library very easy, it can come at a performance cost if your application is not configured
+correctly, since it may draft a schema on every page load. Use automation to help but don't
+let it become a crutch.
+
+## Structure
 
 **Schemas** uses foreign keys, indexes, and naming convention to detect relationships
 automatically. Make sure your database is setup using the appropriate keys and

bin/Schemas.php

@@ -14,6 +14,13 @@ class Schemas extends \Tatter\Schemas\Config\Schemas
 {
 	// Whether to continue instead of throwing exceptions
 	public $silent = true;
+
+	// Which tasks to automate when a schema is not available from the service
+	public $automate = [
+		'draft'   => true,
+		'archive' => true,
+		'read'    => true,
+	];
 
 	//--------------------------------------------------------------------
 	// Drafting

src/Config/Schemas.php

@@ -6,6 +6,13 @@ class Schemas extends BaseConfig
 {
 	// Whether to continue instead of throwing exceptions
 	public $silent = true;
+
+	// Which tasks to automate when a schema is not available from the service
+	public $automate = [
+		'draft'   => true,
+		'archive' => true,
+		'read'    => true,
+	];
 
 	//--------------------------------------------------------------------
 	// Drafting

src/Exceptions/SchemasException.php

@@ -19,4 +19,14 @@ public static function forMethodNotImplemented($class, $method)
 	{
 		return new static(lang('Schemas.methodNotImplemented', [$class, $method]));
 	}
+	
+	public static function forNoSchema()
+	{
+		return new static(lang('Schemas.noSchema'));
+	}
+	
+	public static function forReaderNotReady()
+	{
+		return new static(lang('Schemas.readerNotReady'));
+	}
 }

src/Language/en/Schemas.php

@@ -6,4 +6,6 @@
 	'missingField'         => '{0} is missing {1}',
 	'emptySchemaFile'      => 'Could not read file contents from {0}',
 	'emptySchemaDirectory' => 'No files found in schema directory: {0}',
+	'noSchema'             => 'No schema is available and automation failed or is disabled',
+	'readerNotReady'       => 'Unable to use Reader: not ready',
 ];

src/Reader/BaseReader.php

@@ -4,6 +4,13 @@
 
 class BaseReader extends BaseHandler
 {
+	/**
+	 * Whether the reader is in a state to be used
+	 *
+	 * @var bool
+	 */
+	protected $ready = false;
+
 	/**
 	 * The currently loaded schema.
 	 * Could be static but since Reader is usually called by
@@ -13,6 +20,37 @@ class BaseReader extends BaseHandler
 	 */
 	protected $schema;
 
+	/**
+	 * Indicate whether the reader is in a state to be used
+	 *
+	 * @param array|string $tables
+	 */
+	public function ready(): bool
+	{
+		return $this->ready;
+	}
+
+	/**
+	 * Check that reader is ready before using its functions
+	 *
+	 * @param array|string $tables
+	 */
+	protected function ensureReady(): bool
+	{
+		if ($this->ready)
+		{
+			return true;
+		}
+		
+		if (! $this->config->silent)
+		{
+			throw SchemasException::forReaderNotReady();
+		}
+
+		$this->errors[] = lang('Schemas.notReady');
+		return false;
+	}
+
 	/**
 	 * Dummy implementation for classes that cannot lazy load
 	 *

src/Reader/Handlers/CacheHandler.php

@@ -28,17 +28,22 @@ public function __construct(BaseConfig $config = null, CacheInterface $cache = n
 		$this->cacheInit($cache);
 
 		// Start $tables as the cached scaffold version
-		$scaffold = $this->cache->get($this->cacheKey);
-
-		$this->tables = $scaffold->tables ?? new Mergeable();
+		if ($scaffold = $this->cache->get($this->cacheKey))
+		{
+			if (isset($scaffold->tables))
+			{
+				$this->tables = $scaffold->tables ?? new Mergeable();
+				$this->ready = true;
+			}
+		}
 	}
 
 	/**
 	 * Return the current tables, fetched or not
 	 *
-	 * @return array  String error messages
+	 * @return array|null
 	 */
-	public function getTables(): Mergeable
+	public function getTables(): ?Mergeable
 	{
 		return $this->tables;
 	}
@@ -52,6 +57,11 @@ public function getTables(): Mergeable
 	 */
 	public function fetch($tables)
 	{
+		if (! $this->ensureReady())
+		{
+			return $this;
+		}
+
 		if (is_string($tables))
 		{
 			$tables = [$tables];
@@ -75,6 +85,11 @@ public function fetch($tables)
 	 */
 	public function fetchAll()
 	{
+		if (! $this->ensureReady())
+		{
+			return $this;
+		}
+
 		foreach ($this->tables as $tableName => $value)
 		{
 			if ($value === true)

src/Reader/ReaderInterface.php

@@ -4,6 +4,13 @@
 
 interface ReaderInterface extends \Countable, \IteratorAggregate
 {
+	/**
+	 * Indicate whether the reader is in a state to be used
+	 *
+	 * @return bool
+	 */
+	public function ready(): bool;
+
 	/**
 	 * Fetch specified tables into the scaffold
 	 *

src/Schemas.php

@@ -32,8 +32,11 @@ public function __construct(BaseConfig $config, Schema $schema = null)
 	{
 		$this->config = $config;
 
-		// Store an initial schema
-		$this->schema = $schema ?? new Schema();
+		// Store initial schema
+		if (! is_null($schema))
+		{
+			$this->schema = $schema;
+		}
 	}
 
 	/**
@@ -49,13 +52,78 @@ public function getErrors(): array
 	}
 
 	/**
-	 * Return the current schema
+	 * Reset the current schema and errors
 	 *
-	 * @return Schema  The current schema object
+	 * @return $this
+	 */
+	public function reset()
+	{
+		$this->schema = null;
+		$this->errors = [];
+		
+		return $this;
+	}
+
+	/**
+	 * Set the current schema; used mostly for testing
+	 *
+	 * @return $this
+	 */
+	public function setSchema(Schema $schema)
+	{
+		$this->schema = $schema;
+		
+		return $this;
+	}
+
+	/**
+	 * Return the current schema; if automation is enabled then read or draft a missing schema
+	 *
+	 * @return Schema|null  The current schema object
 	 */
 	public function get(): ?Schema
 	{
-		return $this->schema;
+		if (! is_null($this->schema))
+		{
+			return $this->schema;
+		}
+		
+		// No schema loaded - try the default reader
+		if ($this->config->automate['read'])
+		{
+			$this->read();
+			
+			if (! is_null($this->schema))
+			{
+				return $this->schema;
+			}
+		}
+		
+		// Still no schema - try a default draft
+		if ($this->config->automate['draft'])
+		{
+			$this->draft();
+			
+			if (! is_null($this->schema))
+			{
+				// If the draft succeeded check if we should archive it
+				if ($this->config->automate['archive'])
+				{
+					$this->archive();
+				}
+
+				return $this->schema;
+			}
+		}
+		
+		// Absolute failure
+		if (! $this->config->silent)
+		{
+			throw SchemasException::forNoSchema();
+		}
+
+		$this->errors[] = lang('Schemas.noSchema');
+		return null;
 	}
 
 	/**
@@ -86,7 +154,14 @@ public function draft($handlers = null)
 				$handler = new $handler($this->config);
 			}
 
-			$this->schema->merge($handler->draft());
+			if (is_null($this->schema))
+			{
+				$this->schema = $handler->draft();
+			}
+			else
+			{
+				$this->schema->merge($handler->draft());
+			}
 
 			$this->errors = array_merge($this->errors, $handler->getErrors());
 		}
@@ -153,8 +228,11 @@ public function read($handler = null)
 
 		$this->errors = array_merge($this->errors, $handler->getErrors());
 
-		// Replace the current schema with a new one using the injected readHandler
-		$this->schema = new Schema($handler);
+		// If all went well then set the current schema to a new one using the injected reader
+		if ($handler->ready())
+		{
+			$this->schema = new Schema($handler);
+		}
 
 		return $this;
 	}