mirror/php-adminer
1
0
Fork 0
mirror of https://github.com/vrana/adminer.git synced 2025-08-09 08:06:59 +02:00
Code Issues Releases Wiki Activity

Docs: update

Browse Source
This commit is contained in:
Jakub Vrana
2025-03-28 17:42:41 +01:00
parent 81c5ae33ab
commit 06f0a926dd
1 changed files with 7 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
developing.md
View File

@@ -17,7 +17,7 @@ If authentication fails, a login form is displayed at the same URL, and POST dat
If the user authenticates using the same credentials, the action is performed. If the user authenticates using the same credentials, the action is performed.
All state-changing actions (primarily data modifications, as well as language change or logout) are performed using POST with a CSRF token present. All state-changing actions (primarily data modifications, as well as language change or logout) are performed using POST with a CSRF token present.
This token is unnecessary in modern browsers because Adminer sets cookies as SameSite, but it remains for additional security. Adminer sets cookies as SameSite which adds a second protection but not for vulnerabilities on the same site.
If a POST action succeeds, Adminer redirects the browser to a GET request to prevent accidental re-submission. If a POST action succeeds, Adminer redirects the browser to a GET request to prevent accidental re-submission.
An unsuccessful POST displays the same page with pre-filled form fields. An unsuccessful POST displays the same page with pre-filled form fields.
Refreshing the page attempts the action again, which is useful when errors were resolved in another browser tab. Refreshing the page attempts the action again, which is useful when errors were resolved in another browser tab.
@@ -69,10 +69,8 @@ This class enables Adminer and Adminer Editor (which lacks DDL support) to share
Developers can extend this class to implement customizations, as I do for my projects. Developers can extend this class to implement customizations, as I do for my projects.
A more common method for extending Adminer is the [`Plugins`](/adminer/include/plugins.inc.php) class. A more common method for extending Adminer is the [`Plugins`](/adminer/include/plugins.inc.php) class.
Although its code is somewhat repetitive, it effectively allows developers to create plugins without extending `Adminer` directly. A plugin is simply a class defining any methods from [`Adminer`](/adminer/include/adminer.inc.php).
Since developers are accustomed to defining classes with methods, this approach has a low entry barrier. The `Plugins::__call` method calls all registered plugins until one of them returns non-null.
I considered a hook system (`$hooks->register("tableName", $callback)`, then `$hooks->call("tableName")`), but I prefer the direct call syntax (`$adminer->tableName()`).
Implementing hooks while maintaining this syntax would simply relocate repetitive code.
## Code Style ## Code Style
@@ -132,8 +130,9 @@ Proper line wrapping often requires refactoring, which has caused bugs in the pa
## Comments ## Comments
All functions have doc-comments, but redundancy is avoided. All functions have doc-comments, but redundancy is avoided.
For example, `Db` methods are documented only in [mysql.inc.php](/adminer/drivers/mysql.inc.php), not in other drivers. For example, `Db` methods are documented only in [`db.inc.php`](/adminer/include/db.inc.php), not in the drivers.
`@param` tags include only type and description, based on order. `@param` tags include only params with type [more specific](https://phpstan.org/writing-php-code/phpdoc-types) than the native type declaration or with a comment.
The doc-comments use [aliases](/phpstan.neon) for complex arrays.
Doc-comments are imperative ("Get" instead of "Gets"), start with a capital letter, and do not end with a period. Doc-comments are imperative ("Get" instead of "Gets"), start with a capital letter, and do not end with a period.
Inline comments are useful for linking specifications but are generally avoided for explaining self-explanatory code. Inline comments are useful for linking specifications but are generally avoided for explaining self-explanatory code.
@@ -250,6 +249,7 @@ Includes in Adminer start with `./` to bypass `include_path`, which is unrelated
Compilation also [shrinks](https://github.com/vrana/PhpShrink) PHP code by removing whitespace, comments, and shortening variable names. Compilation also [shrinks](https://github.com/vrana/PhpShrink) PHP code by removing whitespace, comments, and shortening variable names.
This prevents plugins from overwriting Adminer’s variables. This prevents plugins from overwriting Adminer’s variables.
The compiled file is binary, which is valid PHP but not valid UTF-8 - a debatable choice. The compiled file is binary, which is valid PHP but not valid UTF-8 - a debatable choice.
Compilation also removes PHP 7 type declarations to be compatible with PHP 5.
Translations used to occupy a large portion of the compiled file. Translations used to occupy a large portion of the compiled file.
In the source code, translations map English strings to localized versions. In the source code, translations map English strings to localized versions.