{"id":20275531,"url":"https://github.com/workofstan/seablast","last_synced_at":"2026-03-15T18:59:34.573Z","repository":{"id":179364942,"uuid":"653383592","full_name":"WorkOfStan/seablast","owner":"WorkOfStan","description":"A minimalist MVC framework added by composer helps you to create a complex, yet easy to maintain, web application by configuration ONLY.","archived":false,"fork":false,"pushed_at":"2025-03-09T15:39:05.000Z","size":80,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-12T23:02:10.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WorkOfStan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-14T00:35:39.000Z","updated_at":"2025-03-09T15:35:50.000Z","dependencies_parsed_at":"2024-02-17T21:27:13.139Z","dependency_job_id":"e48a536b-154f-483c-bf11-bbdccbdb994d","html_url":"https://github.com/WorkOfStan/seablast","commit_stats":null,"previous_names":["workofstan/seablast"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkOfStan%2Fseablast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkOfStan%2Fseablast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkOfStan%2Fseablast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkOfStan%2Fseablast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WorkOfStan","download_url":"https://codeload.github.com/WorkOfStan/seablast/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244257279,"owners_count":20424130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T13:09:45.452Z","updated_at":"2026-03-15T18:59:34.555Z","avatar_url":"https://github.com/WorkOfStan.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Seablast for PHP\n\n[![Total Downloads](https://img.shields.io/packagist/dt/seablast/seablast.svg)](https://packagist.org/packages/seablast/seablast)\n[![Latest Stable Version](https://img.shields.io/packagist/v/seablast/seablast.svg)](https://packagist.org/packages/seablast/seablast)\n\nThis minimalist MVC framework added by [composer](https://getcomposer.org/) helps you to create a complex, yet easy to maintain, web application by configuration ONLY:\n\n- you configure routes for controller,\n- add models for the app business functionality,\n- optionally modify view templates.\n\nThe framework takes care of logs, database, multiple languages, user friendly HTTP errors, friendly URL.\n\n- See \u003chttps://github.com/WorkOfStan/seablast-dist/\u003e for example of how to use it. It's a public template, so you can start creating your app by duplicating that repository.\n\n## Configuration\n\n- the default environment parameters are set in the [conf/default.conf.php](conf/default.conf.php)\n- if [Seablast Auth](https://github.com/WorkOfStan/seablast-auth) extension is present (i.e. referenced in composer.json), use also its configuration\n- if [Seablast I18n](https://github.com/WorkOfStan/seablast-i18n) extension is present (i.e. referenced in composer.json), use also its configuration\n- everything can be overridden in the web app's `conf/app.conf.php` or even in its local deployment `conf/app.conf.local.php`\n- set the default phinx environment in the phinx configuration: `['environments']['default_environment']` where the database credentials are stored. Then SeablastConfiguration provides access to MySQLi adapter through mysqli() method and PDO adapter through pdo() method.\n- the default `log` directory (both for SeablastMysqli/SeablastPdo query.log and Debugger::log()) can be changed as follows `-\u003esetString(SeablastConstant::SB_LOG_DIRECTORY, APP_DIR . '/log')`. Anyway, only levels allowed by `SeablastConstant::SB_LOGGING_LEVEL` are logged.\n\n## Model\n\nSeablastModel uses model field in APP_MAPPING to invoke the model in the App.\n**Model transforms input into knowledge**, therefore the invoked class MUST have a public method `knowledge()` and expect SeablastConfiguration as a constructor argument.\n\n- SeablastModel also expects Superglobals $superglobals argument (instead of injection like `$model-\u003esetSuperglobals($superglobals);` if required by APP_MAPPING), so that the environment variables are always easily available. (Especially important for APIs.)\n\nThe minimal requirements can be implemented by [SeablastModelInterface](src/SeablastModelInterface.php).\n\n- If model replies with `rest` property, API response is triggered instead of HTML UI. If the default HTTP code should be changed, set it up in the `httpCode` property.\n- If model replies with `redirectionUrl` property, then redirection is triggered (instead of HTML UI) with HTTP code 301. The HTTP code MAY be set to 301, 302 or 303 by the `httpCode` property.\n- If using the default BlueprintWeb.latte, the `title` property is displayed as the page title.\n\n```php\nSeablastConstant::APP_MAPPING = route =\u003e [\n    'model' =\u003e '\\App\\Project\\ResponseModel', // class name of the model,\n    'roleIds' =\u003e '1,2', // comma delimited roleIds permitted to access the route,\n]\n```\n\n## View\n\n- Feel free to use the default latte layout `{layout '../vendor/seablast/seablast/views/BlueprintWeb.latte'}` which can be populated by your local `nav.latte` and `footer.latte`.\n\n### Administration\n\n- By default the route `/poseidon` displays the app administration.\n  It is available only to the admin=1, editor=2 (their IDs are the same as used in Seablast Auth) with different rights.\n  Note: admin can view/edit everything that editor can, so for admin you need to declare only what they can do on top of it.\n\n#### Admin Table Configuration\n\nThis section describes how database tables and their columns are configured for **viewing and editing** in the admin interface, based on **user roles**.\n\nThe configuration is **declarative** and role-driven.\n\n##### Core Concepts\n\nAdmin table access is defined on **three levels**:\n\n1. **Role → Accessible tables** (plus permissions for DELETE_ROW or INSERT_ROW)\n2. **Role → Table → Viewable columns**\n3. **Role → Table → Editable columns**\n\nEach level must be explicitly configured.\n\n##### 1. Granting Table Access to a Role\n\nBefore a table can be displayed or edited, it must be **explicitly allowed** for the given role.\n\n##### Syntax\n\n```php\n-\u003esetArrayString(\n    SeablastConstant::ADMIN_TABLE_VIEW . SeablastConstant::USER_ROLE_X,\n    ['table1', 'table2']\n)\n```\n\n##### Meaning\n\n- Defines which tables are visible to a role\n- If a table is not listed here, it will **not appear at all**, even if columns are defined later\n\n##### Example\n\n```php\n-\u003esetArrayString(\n    SeablastConstant::ADMIN_TABLE_VIEW . SeablastConstant::USER_ROLE_EDITOR,\n    ['audios', 'translations']\n)\n```\n\nThe `EDITOR` role can access the `audios` and `translations` tables.\n\n##### 2. Defining Viewable Columns (READ-ONLY)\n\nViewable columns are displayed in the admin table but **cannot be edited**.\n\n##### Syntax\n\n```php\n-\u003esetArrayArrayString(\n    SeablastConstant::ADMIN_TABLE_VIEW . SeablastConstant::USER_ROLE_X,\n    'table_name',\n    ['column1', 'column2']\n)\n```\n\n##### Meaning\n\n- Defines which columns are shown in the table\n- Columns listed here are **read-only**\n- Columns must **not** be duplicated in the EDIT section\n\n##### Example\n\n```php\n-\u003esetArrayArrayString(\n    SeablastConstant::ADMIN_TABLE_VIEW . SeablastConstant::USER_ROLE_ADMIN,\n    'users',\n    ['id', 'email', 'created', 'last_login']\n)\n```\n\nThe admin can view these columns but cannot modify them.\n\n##### 3. Defining Editable Columns (WRITE)\n\nEditable columns appear as form fields and can be modified.\n\n##### Syntax\n\n```php\n-\u003esetArrayArrayString(\n    SeablastConstant::ADMIN_TABLE_EDIT . SeablastConstant::USER_ROLE_X,\n    'table_name',\n    ['editable_column1', 'editable_column2']\n)\n```\n\n##### Meaning\n\n- Defines which columns can be edited\n- Editable columns automatically appear in edit forms\n- Columns must **not** appear in the VIEW section\n\n##### Example\n\n```php\n-\u003esetArrayArrayString(\n    SeablastConstant::ADMIN_TABLE_EDIT . SeablastConstant::USER_ROLE_ADMIN,\n    'items',\n    ['metadata_text', 'active', 'parent_id', 'order']\n)\n```\n\nThe admin can modify these fields.\n\n##### 4. Important Rule: Column Exclusivity\n\n\u003e **A column may appear only once.**\n\nA column must be defined in **either**:\n\n- `VIEW`\n  **or**\n- `EDIT`\n\nNever in both.\n\n##### Reason\n\n- Prevents UI conflicts\n- Avoids ambiguous form behavior\n- Ensures clear permission boundaries\n\n##### 5. Granting Insert/Delete Row Permissions on a Table to a Role\n\nBefore a user can insert or delete a row in a table, it must be **explicitly allowed** for the given role.\nBe careful with the `DELETE_ROW` permission: deleting a category may trigger a cascading delete.\nThe `INSERT_ROW` permission only makes sense when the user also has the `EDIT` permission.\n\n##### Syntax\n\n```php\n-\u003esetArrayString(\n    SeablastConstant::ADMIN_TABLE_DELETE_ROW . SeablastConstant::USER_ROLE_X,\n    ['table1', 'table2']\n)\n-\u003esetArrayString(\n    SeablastConstant::ADMIN_TABLE_INSERT_ROW . SeablastConstant::USER_ROLE_X,\n    ['table1', 'table2']\n)\n```\n\n##### 6. Configuration Overview\n\n| Level               | Method                  | Purpose                                  |\n| ------------------- | ----------------------- | ---------------------------------------- |\n| Role → Tables       | `setArrayString()`      | Which tables a role can access           |\n| Role → Tables       | `setArrayString()`      | Which tables a role can insert rows into |\n| Role → Tables       | `setArrayString()`      | Which tables a role can delete rows from |\n| Role → Table → VIEW | `setArrayArrayString()` | Read-only columns                        |\n| Role → Table → EDIT | `setArrayArrayString()` | Editable columns                         |\n\n##### 7. Typical Workflow: Adding a New Table\n\n```php\n// Step 1 – Allow table access\n-\u003esetArrayString(\n    SeablastConstant::ADMIN_TABLE_VIEW . SeablastConstant::USER_ROLE_EDITOR,\n    ['new_table']\n)\n\n// Step 2 – Define viewable columns\n-\u003esetArrayArrayString(\n    SeablastConstant::ADMIN_TABLE_VIEW . SeablastConstant::USER_ROLE_EDITOR,\n    'new_table',\n    ['id', 'name']\n)\n\n// Step 3 – Define editable columns\n-\u003esetArrayArrayString(\n    SeablastConstant::ADMIN_TABLE_EDIT . SeablastConstant::USER_ROLE_EDITOR,\n    'new_table',\n    ['name', 'active']\n)\n```\n\n##### Summary\n\n- Table access is **role-based**\n- Columns are explicitly split into **VIEW** and **EDIT**\n- A column may exist in **only one section**\n- Tables must be registered **before** defining columns\n\nThis design guarantees predictable behavior, secure access control, and a clean admin UI.\n\n#### Color editor for selected fields\n\nFields that use the color editor (instead of a textarea) also display the selected color as the background.\nThis feature applies to all fields with the same name across all tables (field names MUST be unambiguous).\n\n```php\n        -\u003esetArrayString(SeablastConstant::ADMIN_COLOR_FIELDS, [\n            'color_main', // audios.color_main but also item.color_main which still makes sense\n        ])\n```\n\n## Authentication and authorisation\n\n- Roles are for access.\n- Routes can be restricted to specific roles (allow-list only; no denies).\n- Menu items can be both allowed and denied (e.g. don't show to an authenticated user).\n- Groups are on top of it, e.g. for promotions, subscriptions etc.\n- RBAC (Role-Based Access Control): SB_IDENTITY_MANAGER provided by application MUST have methods prescribed in [IdentityManagerInterface](https://github.com/WorkOfStan/seablast-interfaces/blob/main/src/IdentityManagerInterface.php), these populate FLAG_USER_IS_AUTHENTICATED and USER_ROLE_ID and also USER_ID.\n\n## Security\n\nAll JSON calls and form submits MUST contain `csrfToken` handed over to the view layer in the `$csrfToken` string latte variable.\n\n## Stack\n\n- PHP \u003e=7.2 \u003c8.6\n- [Latte](http://latte.nette.org/) `\u003e=2.10.8 \u003c4`: For templating.\n- [MySQL](https://dev.mysql.com/)/[MariaDB](http://mariadb.com): For database backend.\n- [Tracy](https://github.com/nette/tracy) `^2.9.8 || ^2.10.9`: For debugging.\n- [Nette\\SmartObject](https://doc.nette.org/en/3.0/smartobject): A trait that helps enforce strict PHP behavior.\n- [jQuery](https://jquery.com/) 3.7.1: As a JavaScript framework.\n- [Universal Language Selector jQuery library](https://github.com/wikimedia/jquery.uls): For language switching (used by [Seablast I18n](https://github.com/WorkOfStan/seablast-i18n)).\n\n### ULS (Universal Language Selector jQuery library)\n\n- if flag `I18nConstant::FLAG_SHOW_LANGUAGE_SELECTOR` is active (default in Seablast\\I18n), then CSS and JS dependencies are already part of the template [BlueprintWeb.latte](views/BlueprintWeb.latte).\n- .eslintignore and .prettierignore to ignore third-party libraries, so that super-linter doesn't fail with JAVASCRIPT_ES and so that prettier doesn't change them or super-linter fails with CSS_PRETTIER, JAVASCRIPT_PRETTIER, JSON_PRETTIER, MARKDOWN_PRETTIER\n- To make the SVG icon in `.uls-trigger` adopt the `font-color` of the surrounding element, the following style was added into `uls/images/language.svg`: `fill=\"currentColor\"`. Also `uls/css/jquery.uls.css` was changed (changed: `.uls-trigger`, added: `.uls-trigger icon` and `.uls-trigger .icon svg`).\n- based on \u003chttps://github.com/wikimedia/jquery.uls\u003e Revision: 077c71408284f446b626b656ce206e6ed3af705c Date: 17.07.2025 14:25:10\n  - css\\jquery.uls.css\n\n    ```css\n    .uls-trigger {\n      background: url(../images/language.svg) no-repeat left center;\n      padding-left: 24px;\n    }\n    ```\n\n    ... changed to ...\n\n    ```css\n    .uls-trigger {\n      padding-left: 24px;\n    }\n\n    .uls-trigger .icon {\n      vertical-align: middle;\n    }\n\n    .uls-trigger .icon svg {\n      height: 1em; /* přizpůsobí velikost textu */\n    }\n    ```\n\n  - images\\language.svg\n\n    ```svg\n    \u003csvg xmlns=\"http://www.w3.org/2000/svg\" width=\"20\" height=\"20\" viewBox=\"0 0 20 20\"\u003e\n    ```\n\n    ... changed to ...\n\n    ```svg\n    \u003csvg xmlns=\"http://www.w3.org/2000/svg\" width=\"20\" height=\"20\" fill=\"currentColor\" viewBox=\"0 0 20 20\"\u003e\n    ```\n\n- See \u003chttps://github.com/wikimedia/jquery.uls/compare/077c71408284f446b626b656ce206e6ed3af705c...master\u003e to compare the changes in the latest version\n\n## Notes\n\n- the constant `APP_DIR` = the directory of the current application (or the library, if deployed directly)\n- don't start the value of a constant for a configuration field in the app.conf.php with SB to prevent value collision\n\n## Framework directory description\n\n| Directory | Description                                                                                                            |\n| --------- | ---------------------------------------------------------------------------------------------------------------------- |\n| .github/  | Automations                                                                                                            |\n| assets/   | Web assets available for browser (such as shared scripts)                                                              |\n| cache/    | Latte cache - this is just for development as production-wise, there will be `cache/` directory in the root of the app |\n| conf/     | Default configuration for a Seablast app and for PHPStan                                                               |\n| log/      | Logs - this one is just for development; as production-wise, there will be `log/` directory in the root of the app     |\n| src/      | Seablast classes                                                                                                       |\n| tests/    | PHPUnit tests                                                                                                          |\n| views/    | Latte templates to be inherited (note: {try}{include file} masks compilation errors by preferring seablast/views)      |\n\n## Testing\n\nThe PHPUnit tests use the database configuration from `./conf/phinx.local.php`, so the library require-dev Phinx, ensuring PHPUnit tests work on GitHub as well.\n\n## Development notes\n\n`./blast.sh phpstan` runs PHPStan to test the repository.\nIt can also be called `./vendor/seablast/seablast/blast.sh` from a Seablast application as a management script for deployment and development. Run `./blast.sh -?` to see all the options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkofstan%2Fseablast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkofstan%2Fseablast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkofstan%2Fseablast/lists"}