IPS DevKit (ips-devkit)

A standalone developer toolkit and deployment tool for IPS Community Suite (≤ v4.7.19). It enables developers to synchronize HTML templates, CSS stylesheets, language strings, settings, friendly URL (FURL) rules, and database migrations from their application's dev/ directory directly to the master theme set without needing the performance-heavy IN_DEV mode enabled on their local or production environment.

🚀 Key Features

• Multi-App Autodiscovery: Automatically scans your IPS /applications/ directory for any custom apps containing a dev/ folder.
• Master Theme Deployment: Deploys raw .phtml templates and .css source files directly to the master theme (set_id = 0) to prevent theme sync issues.
• Automatic Non-Master Cleanup: Automatically deletes compiled non-master templates and CSS rows when deploying modifications to prevent local overrides from blocking your updates.
• DB Schema Migrations: Scans and executes pending database migrations from the application's setup/upg_XX/queries.json and runs custom procedural steps from upgrade.php.
• Resource Synchronizations:
  • Language Strings: Inserts or updates word definitions from data/lang.xml into core_sys_lang_words for all installed languages.
  • Settings: Synchronizes application default configuration parameters from data/settings.json.
  • Friendly URLs: Parses and merges Friendly URL routing rules from data/furl.json directly into the IPS Data Store configuration.
• Safety Backups & Retention: Automatically creates a database backup (as JSON) before every deploy or rollback operation and enforces a backup retention limit (default: 10 backups per app).
• Token-based Authentication: Protects web access with an arbitrary secure secret token configured via a .env environment file.
• CLI Support: Fully featured Command Line Interface supporting automated builds, dry-runs, database migrations, listing backups, and running rollbacks.
• Dark Mode Dashboard: Gorgeous, responsive user interface designed with a dark-theme aesthetic, status badges, update notifications, and real-time scanning.

---

📋 Requirements

• PHP 7.4 or newer (supports PHP 8.x)
• IPS Community Suite version 4.0 up to 4.7.19
• A custom application with a dev/ directory containing source files (e.g. dev/html/ and/or dev/css/)

---

📦 Installation & Setup

1. Download / Clone: Clone this repository into the root directory of your IPS forum installation:

   git clone https://github.com/Pokemon-Millennium/ips-devkit.git ips-devkit

   Note: Place the ips-devkit directory directly inside the forum root alongside init.php.

2. Configure Environment: Copy the template configuration file:

   cp ips-devkit/.env.example ips-devkit/.env

   Open ips-devkit/.env in your text editor and generate a secure random string for the authentication token:

   DEPLOYER_TOKEN=your_super_secure_random_token_here

3. Verify Security: The repository includes a .htaccess file which denies web access to your .env configuration, .gitignore, and the src/ directory. Ensure your web server configuration honors .htaccess directives (AllowOverride All on Apache), or configure equivalent blocks on Nginx:

   location ~ ^/ips-devkit/(\.env|\.git|src/|backups/) {
       deny all;
       return 404;
   }

---

💻 Usage

Web Interface

Access the web interface by navigating to your forum URL with the configured token parameter:

http://yourforum.com/ips-devkit/?token=YOUR_TOKEN

• Overview Page: Lists all discovered custom applications, showing their version and whether they have unsynced template/CSS changes or pending migrations.
• Dashboard Page (?app=<app_key>): Showcases the detailed comparison reports for templates and CSS files, lists action buttons, and provides recovery options.

Command Line Interface (CLI)

Run commands directly from the terminal. If you execute the script without --app, the CLI lists all detected applications:

php ips-devkit/index.php

Scan Differences (Dry Run)

Check for changes without making database updates:

php ips-devkit/index.php --app=marketplace --dry-run

Run Deployment (Deploy templates, CSS, settings, languages, and FURL rules)

php ips-devkit/index.php --app=marketplace --auto

Run Database Migrations

Executes pending DB schema changes:

php ips-devkit/index.php --app=marketplace --migrate

Rollback Database State

List available backups for the app:

php ips-devkit/index.php --app=marketplace --list-backups

Rollback to the latest backup:

php ips-devkit/index.php --app=marketplace --rollback

Rollback to a specific backup file:

php ips-devkit/index.php --app=marketplace --rollback=backup_marketplace_2026-06-11_140000.json

---

⚙️ How it Works & Architecture

1. Bootstrap Phase: When initialized, Config::init() searches the parent directories for the IPS loader init.php. It automatically sets up the environment variables and requires the IPS framework to load its database connection and core autoloader.
2. App Discovery: AppDiscovery::discover() scans the /applications/ directory, ignoring IPS system applications (core, forums, nexus, etc.) and non-development applications (those missing a dev/ directory).
3. Template Compiling Rules: IPS stores templates in core_theme_templates. To make custom templates show up instantly, TemplateDeployer compiles them directly into the master theme set (set_id = 0). It also deletes conflicting templates under themed sets (set_id > 0) to prevent local custom edits from overriding your development code.
4. Cache Invalidation: After any modification, Cache::clearTemplateCache() invalidates the IPS filesystem cache (under datastore/template_<app>_*) and unsets database memory caches in \IPS\Data\Store. Finally, it updates core_themes table caches keys to force the browser to request the fresh compiled assets.

---

🔧 Troubleshooting

1. Changes do not appear on the frontend

• Clear Forum Cache: Go to the Admin Control Panel (ACP) → System → Support → Click Clear System Caches.
• Check Theme Set Conflicts: Ensure you do not have custom edits on specific theme templates that might override the master template. If you do, delete the custom template modifications in ACP → Customization → Themes → Templates.

2. Forbidden 403 / Access Denied

• Check your Token: Ensure the query parameter ?token=XYZ matches the token in ips-devkit/.env.
• Server Blocks: Verify your server configuration isn't blocking access to the folder entirely.

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create your branch: feature/cool-new-feature
2. Follow PSR-12 coding standards.
3. Document any public methods or architectural adjustments.
4. Open a Pull Request detailing the changes and verification steps.

---

📝 License

This project is licensed under the MIT License.