Add ERRATUM.md, UPGRADE.md

CHANGELOG.md

@@ -9,6 +9,8 @@ All notable changes to `Slytherin` will be documented in this file.
 - `ContainerException` in `Container`
 - `RouteInterface` for handling specific routes
 - Support for all versions of `http-interop/http-middleware` (`0.3`, `0.4`, `0.5`)
+- `ERRATUM.md` for changes in `README.md` for specified versions
+- `UPGRADE.md` for documentation on how to upgrade versions with BC breaks
 
 ### Changed
 - Third-party packages in `Routing` extends to Slytherin's `Dispatcher`, `Router`

ERRATUM.md

@@ -0,0 +1,47 @@
+# Erratum
+
+The following are the erratum for each `README.md` found from the previous versions:
+
+## 0.4.0
+
+In this version, the `patricklouys/http` has been removed in favor for PSR-07 (`psr/http-message`). With this, kindly add a package that is compliant to PSR-07 (e.g., `zendframework/zend-diactoros`) in the `composer.json`:
+
+``` diff
+ {
+     "require":
+     {
+         "filp/whoops": "~2.0",
+         "nikic/fast-route": "~1.0",
+-        "patricklouys/http": "~1.0",
+         "rdlowrey/auryn": "~1.0",
+-        "rougin/slytherin": "~0.3.0",
+-        "twig/twig": "~1.0"
++        "rougin/slytherin": "~0.4.0",
++        "twig/twig": "~1.0",
++        "zendframework/zend-diactoros": "~1.0"
+     }
+ }
+```
+
+Perform `composer update` afterwards to update the specified packages.
+
+## 0.3.0
+
+### Usage
+
+As per documentation, implementing interfaces are required to use Slytherin components. However in this release, the implemented third-party packages are not included (e.g., `patricklouys/http`, etc.) and needs to be installed manually. Kindly include the said packages in the `composer.json`:
+
+``` diff
+ {
+     "require":
+     {
++        "filp/whoops": "~1.0",
++        "nikic/fast-route": "~1.0",
++        "patricklouys/http": "~1.0",
++        "rdlowrey/auryn": "~1.0",
+-        "rougin/slytherin": "~0.3.0"
++        "rougin/slytherin": "~0.3.0",
++        "twig/twig": "~1.0"
+     }
+ }
+```

UPGRADE.md

@@ -0,0 +1,269 @@
+# Slytherin Upgrade Guide
+
+Below are the guides when upgrading from specified versions due to backward compatibility breaks:
+
+## From `v0.3.0` to `v0.4.0`
+
+The `v0.4.0` version requires a PSR-07 compliant package. See the `v0.4.0` in `ERRATUM` for updating the `composer.json`.
+
+With the transition to PSR-07, kindly update the following classes from `index.php`:
+
+``` diff
+ use Rougin\Slytherin\Application;
+ use Rougin\Slytherin\ComponentCollection;
+ use Rougin\Slytherin\Dispatching\Dispatcher;
+ use Rougin\Slytherin\ErrorHandler\Whoops;
+-use Rougin\Slytherin\Http\Request;
+-use Rougin\Slytherin\Http\Response;
+ use Rougin\Slytherin\IoC\Auryn;
+ use Rougin\Slytherin\Template\RendererInterface;
+ use Rougin\Slytherin\Template\Twig;
++use Zend\Diactoros\Response;
++use Zend\Diactoros\ServerRequestFactory;
+
+ // ...
+
+-// Initialize the RequestInterface and ResponseInterface -----------------------------
+-$stream = file_get_contents('php://input');
+-$request = new \Http\HttpRequest($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER, $stream);
+-$request = new Request($request);
+-$response = new Response(new \Http\HttpResponse);
++// Initialize the ServerRequestInterface and ResponseInterface ---
++$request = ServerRequestFactory::fromGlobals();
++$response = new Response;
+ $component->setHttp($request, $response);
+-// -----------------------------------------------------------------------------------
++// ---------------------------------------------------------------
+
+ // ...
+```
+
+## From `v0.2.1` to `v0.3.0`
+
+Due to transition from an application project to a micro-framework package, the following updates must be performed:
+
+Update the following details in `composer.json`:
+
+``` diff
+ {
+     "require":
+     {
+-        "rougin/slytherin": "~0.2.0"
++        "filp/whoops": "~2.0",
++        "nikic/fast-route": "~1.0",
++        "patricklouys/http": "~1.0",
++        "rdlowrey/auryn": "~1.0",
++        "rougin/slytherin": "~0.3.0",
++        "twig/twig": "~1.0"
+     },
+     "autoload":
+     {
+         "psr-4":
+         {
+-            "Controllers\\": "app/controllers",
+-            "Libraries\\": "app/libraries",
+-            "Models\\": "app/models"
++            "Rougin\\Nostalgia\\": "src"
+         }
+-    },
+-    "scripts":
+-    {
+-        "post-update-cmd":
+-        [
+-            "Rougin\\Slytherin\\Installer::deploy"
+-        ]
+     }
+ }
+```
+
+**NOTE**: `Rougin\\Nostalgia\\` is only a example namespace. The said namespace can be changed for the whole project.
+
+Then execute `composer update` to update the packages:
+
+``` bash
+$ composer update
+```
+
+After updating, copy the `index.php` to `app/web` directory:
+
+``` diff
++app/
++├─ web/
++│  ├─ index.php
+-index.php
+```
+
+From the `index.php`, paste the following code:
+
+``` php
+use Rougin\Slytherin\Application;
+use Rougin\Slytherin\ComponentCollection;
+use Rougin\Slytherin\Dispatching\Dispatcher;
+use Rougin\Slytherin\ErrorHandler\Whoops;
+use Rougin\Slytherin\Http\Request;
+use Rougin\Slytherin\Http\Response;
+use Rougin\Slytherin\IoC\Auryn;
+use Rougin\Slytherin\Template\RendererInterface;
+use Rougin\Slytherin\Template\Twig;
+
+$root = dirname(dirname(__DIR__));
+
+require $root . '/vendor/autoload.php';
+
+$component = new ComponentCollection;
+
+// Initialize the RendererInterface -------------
+$views = (string) realpath($root . '/app/views');
+$loader = new Twig_Loader_Filesystem($views);
+$twig = new Twig(new Twig_Environment($loader));
+$renderer = RendererInterface::class;
+// ----------------------------------------------
+
+// Initialize the DependencyInjectorInterface ---
+$auryn = new Auryn(new \Auryn\Injector);
+// Create an alias for the RendererInterface ---
+$auryn->share($twig);
+$auryn->alias($renderer, get_class($twig));
+// ---------------------------------------------
+$component->setDependencyInjector($auryn);
+// ----------------------------------------------
+
+// Initialize the ErrorHandlerInterface ---
+$whoops = new Whoops(new \Whoops\Run);
+$component->setErrorHandler($whoops);
+// ----------------------------------------
+
+// Initialize the RequestInterface and ResponseInterface -----------------------------
+$stream = file_get_contents('php://input');
+$request = new \Http\HttpRequest($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER, $stream);
+$request = new Request($request);
+$response = new Response(new \Http\HttpResponse);
+$component->setHttp($request, $response);
+// -----------------------------------------------------------------------------------
+
+// Initialize the routing dispatcher interface ---
+$router = require "$root/app/config/routes.php";
+$dispatcher = new Dispatcher($router, $response);
+$component->setDispatcher($dispatcher);
+// -----------------------------------------------
+
+// Initialize then run the Application ---
+$app = new Application($component);
+
+$app->run();
+// ---------------------------------------
+```
+
+From the `app/config/routes.php` file, change the syntax with the following below:
+
+``` php
+use Rougin\Slytherin\Dispatching\Router;
+
+$name = 'Rougin\Nostalgia\Routes';
+
+$router = new Router;
+
+$router->addRoute('GET', '/', [ "$name\Welcome", 'index' ]);
+
+$router->addRoute('GET', '/users', [ "$name\Users", 'index' ]);
+
+return $router;
+```
+
+Create a `src` directory then copy `controllers`, `libraries`, and `models` to `src/Routes`, `src/Packages`, and `src/Models` respectively:
+
+``` diff
+ app/
+-├─ controllers/
+-├─ packages/
+-├─ models/
++src/
++├─ Models/
++├─ Packages/
++├─ Routes/
+```
+
+Once copied, remove the `extends Controller` in each of the files in the `src/Routes` directory. If the route uses `View`, replace it with `RendererInterface`:
+
+``` diff
+-namespace Controllers;
++namespace Routes;
+
+-use Rougin\Slytherin\Controller;
+-use Rougin\Slytherin\View;
++use Rougin\Slytherin\Template\RendererInterface;
+
+-class Welcome extends Controller
++class Welcome
+ {
++       protected $renderer;
++
++       public function __construct(RendererInterface $renderer)
++       {
++               $this->renderer = $renderer;
++       }
++
+        public function index()
+        {
+-               return View::render('welcome/index');
++               return $this->renderer->render('welcome/index');
+        }
+ }
+```
+
+If using the `View` class for handling templates, rename the files in the `view` directory with `.html`:
+
+``` diff
+ app/
+ ├─ views/
+ │  ├─ users/
++│  │  ├─ index.html
+-│  │  ├─ index.php
+ │  ├─ welcome/
++│  │  ├─ index.html
+-│  │  ├─ index.php
+```
+
+If using the `Model` class for handling database results, replace it with the implementation of `PDO`:
+
+``` diff
+-namespace Models;
++namespace Rougin\Nostalgia\Models;
+
+-use Rougin\Slytherin\Model;
+-
+-class User extends Model
++class User
+ {
+-    public function get($page = 1, $limit = 10)
++    protected $pdo;
++
++    public function __construct()
+     {
+-        $pdo = $this->databaseHandle;
++        $items = require __DIR__ . '/../../app/config/databases.php';
++
++        $data = $items['default'];
++
++        $dsn = "{$data['driver']}:host={$data['hostname']};dbname={$data['database']}";
++
++        $pdo = new \PDO($dsn, $data['username'], $data['password']);
+
++        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
++
++        $this->pdo = $pdo;
++    }
++
++    public function get($page = 1, $limit = 10)
++    {
+         $query = 'SELECT * FROM users';
+
+         $offset = ($page - 1) * $limit;
+
+         $query .= " LIMIT $limit OFFSET $offset";
+
+-        $st = $pdo->prepare($query);
++        $st = $this->pdo->prepare($query);
+
+         $st->execute();
+```