From 6c0f3a336ecac7ba149c3ce7a325b6a3f343bf19 Mon Sep 17 00:00:00 2001 From: Diogo Peralta Cordeiro Date: Tue, 20 Jul 2021 12:35:05 +0100 Subject: [PATCH] [DOCS][Developer] Adopt a top-down approach Minor corrections to the overview --- docs/developer/src/SUMMARY.md | 15 ++++++++++++++- docs/developer/src/core.md | 18 ++++++++++++++++++ docs/developer/src/core/event-dispatcher.md | 0 docs/developer/src/core/files.md | 0 docs/developer/src/core/http.md | 0 docs/developer/src/core/interfaces.md | 0 .../developer/src/core/internationalization.md | 0 docs/developer/src/core/modules.md | 0 docs/developer/src/core/orm_and_caching.md | 0 .../src/{high_level.md => core/overview.md} | 18 +++++++++--------- docs/developer/src/core/queues.md | 0 docs/developer/src/core/security.md | 0 docs/developer/src/core/util.md | 0 docs/developer/src/debugging.md | 0 14 files changed, 41 insertions(+), 10 deletions(-) create mode 100644 docs/developer/src/core.md create mode 100644 docs/developer/src/core/event-dispatcher.md create mode 100644 docs/developer/src/core/files.md create mode 100644 docs/developer/src/core/http.md create mode 100644 docs/developer/src/core/interfaces.md create mode 100644 docs/developer/src/core/internationalization.md create mode 100644 docs/developer/src/core/modules.md create mode 100644 docs/developer/src/core/orm_and_caching.md rename docs/developer/src/{high_level.md => core/overview.md} (89%) create mode 100644 docs/developer/src/core/queues.md create mode 100644 docs/developer/src/core/security.md create mode 100644 docs/developer/src/core/util.md create mode 100644 docs/developer/src/debugging.md diff --git a/docs/developer/src/SUMMARY.md b/docs/developer/src/SUMMARY.md index f077540b3a..a1f0280886 100644 --- a/docs/developer/src/SUMMARY.md +++ b/docs/developer/src/SUMMARY.md @@ -1,6 +1,5 @@ # Summary -- [High level view](./high_level.md) - [Architecture: Modules](./architecture.md) - [Programming Style](./paradigms.md) - [Events](./events.md) @@ -17,7 +16,21 @@ - [Plugins](./plugins.md) - [Configuration](./plugins/configuration.md) - [Initialization and Clean Up](./plugins/lifetime.md) +- [Debugging](./debugging.md) - [Sample Plugins](./sample_plugins.md) - [Injecting Javascript](plugins/sample_plugins/Awesomeness.md) - [Creating a block on the sidebar](plugins/sample_plugins/Sample.md) - [Components](./components.md) +- [Core](./core.md) + - [Overview](./core/overview.md) + - [Modules](./core/modules.md) + - [Event dispatcher](./core/event-dispatcher.md) + - [ORM and Caching](./core/orm_and_caching.md) + - [Interfaces](./core/interfaces.md) + - [UI](./core/ui.md) + - [Internationalization](./core/internationalization.md) + - [Utils](./core/util.md) + - [Queues](./core/queues.md) + - [Files](./core/files.md) + - [Security](./core/security.md) + - [HTTP Client](./core/http.md) \ No newline at end of file diff --git a/docs/developer/src/core.md b/docs/developer/src/core.md new file mode 100644 index 0000000000..ea27c60c19 --- /dev/null +++ b/docs/developer/src/core.md @@ -0,0 +1,18 @@ +# The Core +This documentation adopted a top-down approach. We believed this to be the most helpful as it reduces the time needed +to start developing third party plugins. To contribute to GNU social's core, on the other hand, it's important to +[understand its flows](./core.md) and internals well. + +The `core` tries to be minimal. The essence of it being various wrappers around Symfony. It is divided in: + +- [Modules](./core/modules.md); +- [Event dispatcher](./core/event-dispatcher.md); +- [ORM and Caching](./core/orm_and_caching.md); +- [Interfaces](./core/interfaces.md); +- [UI](./core/ui.md); +- [Internationalization](./core/internationalization.md); +- [Utils](./core/util.md); +- [Queues](./core/queues.md); +- [Files](./core/files.md); +- [Security](./core/security.md); +- [HTTP Client](./core/http.md). \ No newline at end of file diff --git a/docs/developer/src/core/event-dispatcher.md b/docs/developer/src/core/event-dispatcher.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/files.md b/docs/developer/src/core/files.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/http.md b/docs/developer/src/core/http.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/interfaces.md b/docs/developer/src/core/interfaces.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/internationalization.md b/docs/developer/src/core/internationalization.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/modules.md b/docs/developer/src/core/modules.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/orm_and_caching.md b/docs/developer/src/core/orm_and_caching.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/high_level.md b/docs/developer/src/core/overview.md similarity index 89% rename from docs/developer/src/high_level.md rename to docs/developer/src/core/overview.md index f7f9881385..098a66bbb5 100644 --- a/docs/developer/src/high_level.md +++ b/docs/developer/src/core/overview.md @@ -1,4 +1,4 @@ -# GNU social at a high level +# Overview of GNU social's Core Internals GNU social's execution begins at `public/index.php`, which gets called by the webserver for all requests. This is handled by the @@ -30,7 +30,7 @@ The latter, is launched when the `bin/console` script is used. In both cases, these events call the `register` function, which creates static references for the services such as logging, event and -translation. This is done so these services can be used via static +translation. This is done, so these services can be used via static function calls, which is much less verbose and more accessible than the way the framework recommends. This function also loads all the Components and Plugins, which like in V2, are modules that aren't @@ -51,7 +51,7 @@ as in V2, where each 'Entity' has a `schemaDef` static function which returns an array with the database definition. The latter handles the loading of modules (components and plugins). -This datbase definition is handled by the `SchemaDefPass` class, which +This database definition is handled by the `SchemaDefPass` class, which extends `Doctrine\Persistence\Mapping\Driver\StaticPHPDriver`. The function `loadMetadataForClass` is called by the Symfony framework for each file in `src/Entity/`. It allows us to call the @@ -62,17 +62,17 @@ to load the entity definitions from each plugin. ### Routing Next, we'll look at the `RouteLoader`, defined in -`src/Util/RoutLoader.php`, which loads all the files from +`src/Core/Router/RouteLoader.php`, which loads all the files from `src/Routes/*.php` and calls the static `load` method, which defines routes with an interface similar to V2's `connect`, except it requires -an extra identifier as the first argument. This identifier is used, -for instance, to generate URLs for each route. Each route connects an +an additional identifier as the first argument. This identifier is used, +for instance, to generate URLs for each route. Each route connects a URL path to a Controller, with the possibility of taking arguments, which are passed to the `__invoke` method of the respective controller or the given method. The controllers are defined in `src/Controller/` or `plugins/*/Controller` or `components/*/Controller` and are responsible for handling a request and return a Symfony `Response` -object or an array that gets converted to one (subject to change, in +object, or an array that gets converted to one (subject to change, in order to abstract HTML vs JSON output). This array conversion is handled by `App\Core\Controller`, along with @@ -85,11 +85,11 @@ JSON, with what the controller returned. The next steps are handled by the Symfony framework which creates a `Request` object from the HTTP request, and then a corresponding `Response` is created by `App\Core\Controller`, which matches the -appropriate route and thus calls it's controller. +appropriate route and thus calls its controller. ### Performance -All this happens on each request, which seems like a lot to handle, +All of this happens on each request, which seems like a lot to handle, and would be too slow. Fortunately, Symfony has a 'compiler' which caches and optimizes the code paths. In production mode, this can be done through a command, while in development mode, it's handled on diff --git a/docs/developer/src/core/queues.md b/docs/developer/src/core/queues.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/security.md b/docs/developer/src/core/security.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/core/util.md b/docs/developer/src/core/util.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/debugging.md b/docs/developer/src/debugging.md new file mode 100644 index 0000000000..e69de29bb2