{"id":48380994,"url":"https://github.com/wrobeltomasz/open-sparrow","last_synced_at":"2026-04-29T23:13:04.588Z","repository":{"id":344480319,"uuid":"1051808894","full_name":"wrobeltomasz/open-sparrow","owner":"wrobeltomasz","description":"Open source | LGPL v3. | PHP + vanilla JS + Postgres!","archived":false,"fork":false,"pushed_at":"2026-04-23T20:02:46.000Z","size":927,"stargazers_count":4,"open_issues_count":4,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T21:31:23.512Z","etag":null,"topics":["content-management","crm","crud","data-grid","erp","grid-system","internal-tool","java-vanilla","low-code","lowcode","no-code","nocode","opensource","php","postgresql","postgresql-database","self-hosted","web-application","wms"],"latest_commit_sha":null,"homepage":"https://opensparrow.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wrobeltomasz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2025-09-06T19:04:05.000Z","updated_at":"2026-04-23T19:55:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wrobeltomasz/open-sparrow","commit_stats":null,"previous_names":["wrobeltomasz/open-sparrow"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/wrobeltomasz/open-sparrow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrobeltomasz%2Fopen-sparrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrobeltomasz%2Fopen-sparrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrobeltomasz%2Fopen-sparrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrobeltomasz%2Fopen-sparrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wrobeltomasz","download_url":"https://codeload.github.com/wrobeltomasz/open-sparrow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrobeltomasz%2Fopen-sparrow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32242315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["content-management","crm","crud","data-grid","erp","grid-system","internal-tool","java-vanilla","low-code","lowcode","no-code","nocode","opensource","php","postgresql","postgresql-database","self-hosted","web-application","wms"],"created_at":"2026-04-05T20:03:20.293Z","updated_at":"2026-04-29T23:13:04.569Z","avatar_url":"https://github.com/wrobeltomasz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg width=\"100\" height=\"100\" alt=\"opensparrow-logo\" src=\"https://github.com/user-attachments/assets/b4793826-edc3-4ede-99e1-bdbd9c12f0bb\" /\u003e\n\n  \u003ch1\u003eOpenSparrow\u003c/h1\u003e\n\n  \u003cp\u003e\u003cstrong\u003eSchema-driven PHP platform to build CRUD apps, dashboards, and calendars on PostgreSQL in minutes.\u003c/strong\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"LICENCE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-LGPL%20v3-blue.svg\" alt=\"License: LGPL v3\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.php.net/\"\u003e\u003cimg src=\"https://img.shields.io/badge/PHP-8.1%2B-777BB4?logo=php\u0026logoColor=white\" alt=\"PHP 8.1+\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript\"\u003e\u003cimg src=\"https://img.shields.io/badge/JavaScript-ES6%2B-F7DF1E?logo=javascript\u0026logoColor=black\" alt=\"JavaScript ES6+\" /\u003e\u003c/a\u003e\n    \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/dependencies-none-brightgreen\" alt=\"No dependencies\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\n  ![E2E Tests](https://github.com/wrobeltomasz/open-sparrow/actions/workflows/e2e-tests.yml/badge.svg)\n  ![CodeQL Analysis](https://github.com/wrobeltomasz/open-sparrow/actions/workflows/codeql.yml/badge.svg)\n  ![Docker Lint](https://github.com/wrobeltomasz/open-sparrow/actions/workflows/docker-lint.yml/badge.svg)\n  [![Release ZIP](https://github.com/wrobeltomasz/open-sparrow/actions/workflows/release-zip.yml/badge.svg)](https://github.com/wrobeltomasz/open-sparrow/actions/workflows/release-zip.yml)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\nOpenSparrow is a JSON schema-driven platform for building internal systems. Tables, forms, dashboards, and calendars are generated from configuration files, so business logic stays decoupled from infrastructure. Self-hosted on PostgreSQL — no vendor lock-in, full data ownership.\n\n\u003e **No Composer. No npm. No build step.**  \n\u003e Drop the files, point to PostgreSQL, open `/admin`. That's it.\n\nDemo: https://demo.opensparrow.org\n\n---\n\n## Preview\n\n\u003cimg width=\"1720\" height=\"692\" alt=\"20260420_banner\" src=\"https://github.com/user-attachments/assets/0da4a0c6-667f-4559-87fc-1cb0a729473f\" /\u003e\n\n---\n\n## Features\n\n- **Zero-configuration setup** — configure PostgreSQL and initialize system tables from the admin UI.\n- **JSON-driven CRUD** — tables and forms generated from `schema.json` with nested relations, constraints, and enum color states.\n- **Inline editing** — in-grid PATCH updates routed through a single `api.php` gateway.\n- **Dashboard engine** — COUNT / SUM / AVG / MIN / MAX / GROUP BY widgets defined in `dashboard.json`.\n- **Calendar \u0026 notifications** — date-based records on a calendar view, with scheduled reminders via cron.\n- **Admin panel** — visual editors for schema, dashboards, calendar, users, and security at `/admin`.\n- **Audit logging** — data changes tracked in internal log tables.\n- **CSV export \u0026 pagination** — built-in grid utilities.\n- **Workflows builder** — multi-step wizards linking parent/child records across tables.\n- **File management** — per-record attachments with tagging and search, configurable via the admin panel.\n- **WCAG 2.1 focus** — accessibility-oriented UI.\n- *(Planned)* REST API and webhook engine for n8n / Make / custom integrations.\n\n---\n\n## Project Structure\n\n### Core directories\n- **`admin/`** — management panel (schema editor, users, security settings).\n- **`assets/`** — static frontend resources (`css/`, `js/`, `icons/`, `img/`).\n- **`includes/`** — backend helpers. `config.php` centralizes env-driven configuration; `db.php` centralizes PostgreSQL access; `api_helpers.php` holds request/response helpers.\n- **`cron/`** — scheduled workers (e.g. `cron_notifications.php`).\n- **`templates/`** — layout wrappers (`template.php`).\n- **`tests/`** — E2E Selenium suite.\n- **`storage/files/`** — user-uploaded files.\n\n### Key files\n- **`api.php`** — main API gateway (GET / POST / PATCH / DELETE).\n- **`index.php`** — default landing / data entry page.\n- **`dashboard.php` / `calendar.php`** — user-facing visualization and scheduling modules.\n- **`login.php` / `logout.php`** — session and authentication.\n- **`create.php` / `edit.php`** — record create/update forms.\n- **`api_schema.php`** — filtered schema endpoint for the frontend (hides backend-only structure).\n- **`api_fk.php`** — proxy endpoint for foreign-key dropdowns (never exposes internal relations).\n- **`Dockerfile` / `docker-compose.yml`** — containerized deployment.\n- **`phpcs.xml`** — PSR-12 ruleset.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- PHP 8.1+\n- PostgreSQL 14+\n- Apache, Nginx, or the PHP built-in server\n- Git\n\n### 1. Clone\n\n```bash\ngit clone https://github.com/wrobeltomasz/open-sparrow.git\ncd open-sparrow\n```\n\n### 2. Install via ZIP (FTP / shared hosting)\n\nIf you are deploying to shared hosting or any server without Docker, download the pre-built ZIP from the [Releases page](https://github.com/wrobeltomasz/open-sparrow/releases/latest) instead of cloning.\n\nEach release ZIP is built automatically by GitHub Actions and includes:\n- All PHP, JS, and CSS files ready to serve\n- `includes/VERSION` stamped with the release tag (e.g. `v1.2.3`) — used by the admin System Health panel to display the current version\n- An empty `storage/files/` directory placeholder\n\n**Steps:**\n\n1. Download `opensparrow-vX.Y.Z.zip` from the Releases page.\n2. Extract and upload the contents to your server root (e.g. `public_html/`) via FTP.\n3. Create the `includes/` directory and make it writable by the web server.\n4. Open `/admin` in your browser and configure the database connection.\n5. Run **Initialize System Tables** from the System Health tab.\n\n\u003e **Note:** The ZIP contains no JSON configuration files. Your `includes/*.json` files are never overwritten during an upload — existing configuration is always preserved.\n\n### 3. Run with Docker (quick start)\n\n```bash\n# Create required directories\nmkdir -p includes storage/files\n\n# Set permissions (82:82 is www-data in Alpine)\nsudo chown -R 82:82 includes/ storage/\nsudo chmod -R 775 includes/ storage/\n\n# Start the stack (PHP + Nginx + PostgreSQL)\ndocker compose up -d --build\n```\n\nAvailable at **http://localhost:8080**.\n\n### 4. Dependencies\n\nNone. The repository has no composer/npm step.\n\n### 5. Environment variables (optional)\n\nAll variables are read by `includes/config.php` on every request. If a variable is absent, the documented default applies.\n\n| Variable | Default | Description |\n|---|---|---|\n| `APP_ENV` | `production` | Runtime environment. Set to `development` to enable `SameSite=Lax` cookies (required on HTTP). |\n| `SECURE_COOKIES` | `true` | Set to `false` when running on plain HTTP (local dev, Docker on localhost). |\n| `DB_HOST` | `localhost` | PostgreSQL host. Falls back to `PGHOST` if `DB_HOST` is unset. |\n| `DB_PORT` | `5432` | PostgreSQL port. Falls back to `PGPORT` if `DB_PORT` is unset. |\n| `PGDATABASE` | — | PostgreSQL database name. |\n| `PGUSER` | — | PostgreSQL user. |\n| `PGPASSWORD` | — | PostgreSQL password. |\n| `PGSCHEMA` | `app` | Schema for OpenSparrow system tables (`spw_*`). Overridden by `schema` key in `includes/database.json`. |\n\n\u003e There is no `.env` loader. Export these in your shell, container environment, or web-server virtual-host config. All connection details can alternatively be configured from the admin UI (written to `includes/database.json`).\n\n**Docker dev shortcut:** `docker-compose.override.yml` (included in the repo) sets `APP_ENV=development` and `SECURE_COOKIES=false` automatically when you run `docker compose up` locally.\n\n### 6. Configure the database from Admin\n\nOpen **http://localhost:8080/admin** and log in with the default master password: `admin` *(no username — the admin panel asks only for a master password)*.\n\nIn the **Database** tab:\n\n1. Enter host, port, database, username, and password.\n2. *(Optional)* In **System Schema**, set the PostgreSQL schema for OpenSparrow system tables (`spw_users`, `spw_files`, etc.). Defaults to `app`.\n3. Click **Save File**.\n\nSettings are written to `includes/database.json`. The `schema` key is read by `sys_schema()` in `includes/db.php` and used to qualify every system-table query.\n\n### 7. Initialize system tables\n\nIn the admin panel → **System Health** → **Initialize System Tables**. This creates all `spw_`-prefixed tables in the configured schema:\n\n- `spw_users`\n- `spw_users_log`\n- `spw_users_notifications`\n- `spw_users_notifications_log`\n- `spw_files`\n- `spw_login_attempts`\n\nRe-run this after every upgrade — it uses `CREATE TABLE IF NOT EXISTS` and `ALTER TABLE … ADD COLUMN IF NOT EXISTS`, so it is safe to execute on an existing database.\n\n### 8. Run without Docker\n\n*Skip this if you used Docker in step 2.*\n\n**Option A** — serve via Apache/Nginx and open:\n```\nhttp://localhost/open-sparrow/\n```\n\n**Option B** — PHP built-in server:\n```bash\nphp -S localhost:8000\n```\nOpen **http://localhost:8000/admin**.\n\n---\n\n## Updating via FTP\n\n1. Go to the [Releases page](https://github.com/wrobeltomasz/open-sparrow/releases/latest) and download the latest `opensparrow-vX.Y.Z.zip`.\n2. **Before uploading** — export your configuration from the admin panel: **Configuration → Export config files**. Keep this backup safe.\n3. Extract the ZIP and upload all files to your server via FTP, overwriting existing files.\n4. Your `includes/*.json` files are **not included** in the ZIP, so your database connection, schema, dashboards, and all other settings are preserved automatically.\n5. Log in to `/admin` → **System Health** → **Initialize System Tables** to apply any new system table migrations.\n6. Check **System Health** — the version shown should match the release tag you just uploaded.\n\n---\n\n## Security \u0026 Configuration\n\nConfiguration lives in `includes/database.json`, protected by `.htaccess`. Environment variables (see section 5) take precedence and are the recommended approach for containerized deployments.\n\n- **Production:** deny public web access to `includes/` at the web-server level.\n- **Cookies:** `SECURE_COOKIES=true` (default) enforces the `Secure` flag. Set to `false` only on plain HTTP environments.\n\n---\n\n## Contributing\n\nContributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and sign the [Contributor License Agreement (CLA)](CLA.md) before opening a pull request.\n\n---\n\n## License\n\nLicensed under the **GNU Lesser General Public License v3.0 (LGPL v3)**. You may use OpenSparrow in open-source and closed-source commercial projects. Modifications to core OpenSparrow files must remain under the same license. See [LICENCE](LICENCE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrobeltomasz%2Fopen-sparrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwrobeltomasz%2Fopen-sparrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrobeltomasz%2Fopen-sparrow/lists"}