Merge pull request #4 from dotkernel/arhimede

arhimede · web-flow · commit 7dcb9e51a201 · 2024-05-17T12:06:39.000+03:00
reorganize the documentation items
diff --git a/docs/book/v4/installation/composer.md b/docs/book/v4/installation/composer.md
@@ -0,0 +1,27 @@
+# Composer Installation of Packages
+
+## Install dependencies
+
+```shell
+composer install
+```
+
+## Development mode
+
+If you're installing the project for development, make sure you have development mode enabled, by running:
+
+```shell
+composer development-enable
+```
+
+You can disable development mode by running:
+
+```shell
+composer development-disable
+```
+
+You can check if you have development mode enabled by running:
+
+```shell
+composer development-status
+```
diff --git a/docs/book/v4/installation/configuration-files.md b/docs/book/v4/installation/configuration-files.md
@@ -0,0 +1,20 @@
+# Configuration Files
+
+## Prepare config files
+
+* duplicate `config/autoload/cors.local.php.dist` as `config/autoload/cors.local.php` 
+#### Note
+> if your API will be consumed by another application, make sure to configure the `allowed_origins` variable
+
+* duplicate `config/autoload/local.php.dist` as `config/autoload/local.php`
+
+* duplicate `config/autoload/mail.local.php.dist` as `config/autoload/mail.local.php` 
+
+### Note
+> if your API will send emails, make sure to fill in SMTP connection params
+
+
+* **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php`
+
+### Note
+> this creates a new in-memory database that your tests will run on.
diff --git a/docs/book/v4/installation/doctrine-orm.md b/docs/book/v4/installation/doctrine-orm.md
@@ -0,0 +1,47 @@
+# Doctrine ORM
+
+## Setup database
+
+Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`.
+
+Create a new MySQL database - set collation to `utf8mb4_general_ci`
+
+## Running migrations
+
+Run the database migrations by using the following command:
+
+```shell
+php vendor/bin/doctrine-migrations migrate
+```
+
+This command will prompt you to confirm that you want to run it.
+
+> WARNING! You are about to execute a migration in database "..." that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:
+
+Hit `Enter` to confirm the operation.
+
+## Executing fixtures
+
+**Fixtures are used to seed the database with initial values and should be executed after migrating the database.**
+
+To list all the fixtures, run:
+
+```shell
+php bin/doctrine fixtures:list
+```
+
+This will output all the fixtures in the order of execution.
+
+To execute all fixtures, run:
+
+```shell
+php bin/doctrine fixtures:execute
+```
+
+To execute a specific fixture, run:
+
+```shell
+php bin/doctrine fixtures:execute --class=FixtureClassName
+```
+
+More details on how fixtures work can be found here: https://github.com/dotkernel/dot-data-fixtures#creating-fixtures
diff --git a/docs/book/v4/installation/faq.md b/docs/book/v4/installation/faq.md
@@ -0,0 +1,36 @@
+# Frequently Asked Questions
+
+## How do I fix common permission issues?
+
+If running your project you encounter some permission issues, follow the below steps.
+
+### Errors:
+
+> PHP Fatal error:  Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/data" is not writable...
+
+> PHP Fatal error:  Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/data/cache" is not writable...
+
+> PHP Fatal error:  Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/data/cache/doctrine" is not writable...
+
+**Fix:**
+
+```shell
+chmod -R 777 data
+
+### Error:
+
+> PHP Fatal error:  Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/public/uploads" is not writable...
+
+**Fix:**
+
+```shell
+chmod -R 777 public/uploads
+
+### Error:
+
+> PHP Fatal error:  Uncaught ErrorException: fopen(/var/www/_example.local_/config/autoload/../../log/error-log-_yyyy-mm-dd.log_): Failed to open stream: Permission denied...
+
+**Fix:**
+
+```shell
+chmod -R 777 log
diff --git a/docs/book/v4/installation/getting-started.md b/docs/book/v4/installation/getting-started.md
diff --git a/docs/book/v4/installation/test-the-installation.md b/docs/book/v4/installation/test-the-installation.md
@@ -0,0 +1,31 @@
+# Test the installation
+
+Sending a GET request to the [home page](http://0.0.0.0:8080/) should output the following message:
+
+> {"message": "Welcome to DotKernel API!"}
+
+## Old way of doing things, using PHP built-in server
+
+```shell
+php -S 0.0.0.0:8080 -t public
+```
+
+## Running tests
+
+The project has 2 types of tests: functional and unit tests, you can run both types at the same type by executing this command:
+
+```shell
+php vendor/bin/phpunit
+```
+
+## Running unit tests
+
+```shell
+vendor/bin/phpunit --testsuite=UnitTests --testdox --colors=always
+```
+
+## Running functional tests
+
+```shell
+vendor/bin/phpunit --testsuite=FunctionalTests --testdox --colors=always
+```
diff --git a/docs/book/v4/introduction/installation.md b/docs/book/v4/introduction/installation.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -10,11 +10,16 @@ nav:
   - v4:
       - Introduction:
           - "Introduction": v4/introduction/introduction.md
-          - "Getting Started": v4/introduction/getting-started.md
           - "Server Requirements": v4/introduction/server-requirements.md
           - "File Structure": v4/introduction/file-structure.md
-          - "Installation": v4/introduction/installation.md
           - "Packages": v4/introduction/packages.md
+      - Installation:
+          - "Getting Started": v4/installation/getting-started.md
+          - "Composer": v4/installation/composer.md
+          - "Configuration Files": v4/installation/configuration-files.md
+          - "Doctrine ORM": v4/installation/doctrine-orm.md
+          - "Test the Installation": v4/installation/test-the-installation.md
+          - "FAQ": v4/installation/faq.md
       - Tutorials:
           - "Creating a book module": v4/tutorials/create-book-module.md
       - Transition from API Tools:
