{"id":22663127,"url":"https://github.com/osmphp/admin","last_synced_at":"2025-04-12T07:22:22.874Z","repository":{"id":43923903,"uuid":"419629769","full_name":"osmphp/admin","owner":"osmphp","description":"A package for defining data structures using PHP 8 classes and attributes, and getting fully functioning Admin Panel and API.","archived":false,"fork":false,"pushed_at":"2022-07-23T21:35:51.000Z","size":4259,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"v0.3","last_synced_at":"2025-03-26T02:34:59.217Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://osm.software/blog/data/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osmphp.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-21T07:48:52.000Z","updated_at":"2024-01-25T17:03:04.000Z","dependencies_parsed_at":"2022-07-26T10:18:22.438Z","dependency_job_id":null,"html_url":"https://github.com/osmphp/admin","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmphp%2Fadmin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmphp%2Fadmin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmphp%2Fadmin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmphp%2Fadmin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osmphp","download_url":"https://codeload.github.com/osmphp/admin/tar.gz/refs/heads/v0.3","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248531087,"owners_count":21119693,"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-12-09T12:17:20.236Z","updated_at":"2025-04-12T07:22:22.855Z","avatar_url":"https://github.com/osmphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Osm Admin is a framework for defining database tables using PHP classes and having a user-friendly admin panel for managing data out of the box.\n\nThe ultimate goal to is for you to stop worrying about all the admin panel details of your application, and spend all your efforts on what actually matter to *your* users.\n\nCurrently, it's in active development. The rest of the document is written in present tense, but most of it is yet to be implemented.\n\n## Prerequisites\n\n* [PHP 8.1 or later](https://www.php.net/manual/en/install.php), and enable `curl`, `fileinfo`, `intl`, `mbstring`, `openssl`, `pdo_mysql`, `pdo_sqlite`, `sqlite3`\n  extensions\n* [MySql 8.0 or later](https://dev.mysql.com/downloads/)\n* [Node.js, the latest LTS version](https://nodejs.org/en/download/current/)\n* [Gulp 4 command line utility](https://gulpjs.com/docs/en/getting-started/quick-start#install-the-gulp-command-line-utility)\n* [ElasticSearch 7.14 or later](https://www.elastic.co/downloads/elasticsearch)\n* [Osm Framework command line aliases](https://osm.software/blog/21/08/framework-command-line-aliases.html)\n\n## Getting Started\n\n1. Create a project:\n\n        composer create-project osmphp/admin-project project1\n\n2. Create MySql database, for example `project1`. Avoid `_` and `-` symbols in the name.\n3. In the project directory, create `.env.Osm_App` file. On Linux, use `bin/create-env.sh` command to create it from a template:\n\n        NAME=... # same as MySql database name\n        #PRODUCTION=true\n        \n        MYSQL_DATABASE=\"${NAME}\"\n        MYSQL_USERNAME=...\n        MYSQL_PASSWORD=...\n        \n        SEARCH_INDEX_PREFIX=\"${NAME}_\" \n\n4. Install the project. On Linux, run `bin/install.sh` in the project directory. On other platforms, run the following commands:\n\n        # go to project directory\n        cd project1\n         \n        # compile the applications\n        osmc Osm_Admin_Samples\n        osmc Osm_Project\n        osmc Osm_Tools\n        \n        # collect JS dependencies from all installed modules\n        osmt config:npm\n        \n        # install JS dependencies\n        npm install\n        \n        # build JS, CSS and other assets\n        gulp\n        \n        # make `temp` directory writable\n        find temp -type d -exec chmod 777 {} \\;\n        find temp -type f -exec chmod 666 {} \\;\n        \n        # create tables in the MySql database\n        osm migrate:up --fresh\n\n5. Create and enable a [Nginx virtual host](https://osm.software/docs/framework/0.15/getting-started/web-server.html#nginx), for example, `project1.local`.\n\n       osmt config:nginx --prevent_network_access\n       sudo php vendor/osmphp/framework/bin/tools.php config:host\n       sudo php vendor/osmphp/framework/bin/tools.php install:nginx\n\n6. In a separate command line window, keep Gulp running, it will clear the cache and rebuild assets as needed:\n\n         cd project1\n         gulp \u0026\u0026 gulp watch\n\n7. Define a data class:\n\n        # src/Welcome/Product.php\n        \u003c?php\n        \n        namespace My\\Welcome;\n        \n        use Osm\\Admin\\Schema\\Record;\n        \n        /**\n         * @property string $sku\n         * @property string $description\n         */\n        class Product extends Record\n        {\n        }\n\n8. Open the application in the browser:\n\n        http://project1.local/admin/products/\n\n9. It should work as shown in [this video](https://www.youtube.com/watch?v=SrxXZa5SeMk).\n\n## How It Works\n\nPHP attributes in table definitions are used to specify how properties are stored, validated, computed as well as to define their UI behavior.\n\nTable definitions (PHP classes) are parsed into *schema* - a set of PHP objects having all the information about tables and properties.\n\nSchema changes are detected using a *diff algorithm* and applied to the database, automatically.\n\nThe `query()` function retrieves/modifies table data in bulks using SQL-like *formulas* and the current schema.\n\nWhen data is modified, computed properties and search indexes that depend on it are *re-indexed*.\n\nThe `ui_query()` function adds faceted/search queries on the top of what the `query()` function does.\n\nBased on table definitions, UI *grids* and *forms* are created, automatically. These views:\n\n* provide HTTP routes for every table;\n* register themselves in the main menu;\n* are rendered using Laravel Blade templates and Tailwind CSS;\n* attach client-size behavior to HTML elements, written in vanilla JS.\n\nUI *controls* define how different properties behave in grids and forms.\n\n## Features\n\n1. Effortless changes of data structure while preserving existing data.\n2. Faceted navigation and full-text search in every table.\n3. Multi-record editing.\n4. Unlimited number of properties.\n5. Table class definition and data input validation.\n6. Computed and overridable properties.\n7. Table relations.\n8. Multi-value properties.\n9. ... and more.\n\n## Contributing\n\n### Installation\n\n1. Clone the project to your machine. If you don't have write access to the `osmphp/admin` repository, fork the project on [GitHub](https://github.com/osmphp/admin) to your account, and use your account name instead of `osmphp` in the following command:\n\n        cd ~/projects\n        git clone git@github.com:osmphp/admin.git admin \n\n2. Create MySql database, for example `admin`. Avoid `_` and `-` symbols in the name.\n3. In the project directory, create `.env.Osm_Admin_Samples` file. On Linux, use `bin/create-env.sh` command to create it from a template:\n\n        NAME=... # same as MySql database name\n        #PRODUCTION=true\n        \n        MYSQL_DATABASE=\"${NAME}\"\n        MYSQL_USERNAME=...\n        MYSQL_PASSWORD=...\n        \n        SEARCH_INDEX_PREFIX=\"${NAME}_\" \n\n4. Install the project. On Linux, run `bin/install.sh` in the project directory. On other platforms, run the following commands:\n\n        # go to project directory\n        cd admin\n         \n        # install dependencies\n        composer install\n        \n        # compile the applications\n        osmc Osm_Admin_Samples\n        osmc Osm_Project\n        osmc Osm_Tools\n        \n        # collect JS dependencies from all installed modules\n        osmt config:npm\n        \n        # install JS dependencies\n        npm install\n        \n        # build JS, CSS and other assets\n        gulp\n        \n        # make `temp` directory writable\n        find temp -type d -exec chmod 777 {} \\;\n        find temp -type f -exec chmod 666 {} \\;\n        \n        # create tables in the MySql database\n        php bin/run.php migrate:up --fresh\n\n5. Create and enable a [Nginx virtual host](https://osm.software/docs/framework/0.15/getting-started/web-server.html#nginx), for example, `admin.local`. Use the commands below. In the `osmt config:nginx` command, consider adding the `--prevent_network_access` flag to make the website only available on your computer, but not the surrounding ones:\n\n       osmt config:nginx --app=Osm_Admin_Samples --prevent_network_access\n       sudo php vendor/osmphp/framework/bin/tools.php \\\n           config:host --app=Osm_Admin_Samples\n       sudo php vendor/osmphp/framework/bin/tools.php \\\n           install:nginx --app=Osm_Admin_Samples\n\n6. Open the product list page, \u003chttp://admin.local/admin/products/\u003e.\n\n7. Instead of `osm` command-line alias, use `php bin/run.php`, for example:\n\n        php bin/run.php refresh\n        php bin/run.php migrate:up --fresh \n\n8. In a separate command line window, keep Gulp running, it will clear the cache and rebuild assets as needed:\n\n         cd {project_dir}\n         gulp \u0026\u0026 gulp watch\n\n### Points Of Interest\n\nAfter the project is up and running, put the project under debugger, try various operations in the browser, and in the command line, using `osm` command alias.\n\nTo better understand what's going on under the hood, put breakpoints in main entry points:\n\n* In the `run()` methods of route (or controller) classes, located in the `src/Ui/Routes/Admin` directory.\n* In the `run()` methods of command line commands, located in the `src/Schema/Commands` directory.\n\n### Read Framework Docs\n\nThis project is based on Osm Framework. To better understand how and why this project is written, read [the documentation](https://osm.software/docs/framework/0.15/index.html) of Osm Framework.\n\n### Join Chats\n\nFinally, with all the questions and ideas, join the chats on [Discord](https://discord.gg/EfW4nXPj).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmphp%2Fadmin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosmphp%2Fadmin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmphp%2Fadmin/lists"}