Add comprehensive symlinks and routing system documentation for developers

[Copilot]

ImpressCMS symlinks (database-driven URL mappings in the icmspage table) lack documentation for developers wanting to build custom routing solutions. This creates a barrier for extending the routing system.

Changes

• Added docs/symlinks-and-routing.md (1,490 lines)

  • Database architecture: icmspage table structure and field semantics (page_id, page_moduleid, page_url, page_status)
  • Core classes: icms_data_page_Object, icms_data_page_Handler, SystemPages, SystemPagesHandler with file locations
  • Routing integration: icms_view_PageBuilder::getPage() lifecycle and URL matching (exact + wildcard)
  • 35+ working code examples covering CRUD operations, custom router implementation, handler extensions
  • Security patterns: input validation, output encoding, permission checks, SQL injection prevention
  • Real-world implementations: SEO URLs, block positioning, multi-language routing, centralized URL management

• Updated README.md

  • Added developer documentation section with link to new guide

Example Usage

// Create custom router leveraging symlinks
$page_handler = icms::handler('icms_data_page');
$criteria = new icms_db_criteria_Compo();
$criteria->add(new icms_db_criteria_Item('page_url', $url));
$criteria->add(new icms_db_criteria_Item('page_status', 1));

$pages = $page_handler->getObjects($criteria);
if (count($pages) > 0) {
    $module_id = $pages[0]->getVar('page_moduleid');
    // Route to module based on symlink mapping
}

Target audience: Junior PHP developers building on ImpressCMS core routing.

Original prompt

Create comprehensive documentation explaining how symlinks work in ImpressCMS core and how they can be used to construct a routing system. This guide should be written for junior PHP developers with the goal of using the existing symlink functionality in ImpressCMS to build custom routing solutions.

The documentation should cover:

1. What are Symlinks in ImpressCMS? - Explain that symlinks are database records (not Unix system links) that map human-friendly URLs to specific modules/pages

2. How Symlinks Work - Describe the symlink lifecycle:

   • Symlink records stored in the icmspage database table
   • Key fields: page_id, page_title, page_url, page_status, page_moduleid
   • Where they're managed (System Module > Symlink Manager)
   • How routing logic interacts with them

3. Key Classes and Files - Document:

   • SystemPages class (extends icms_data_page_Object)
   • SystemPagesHandler class (extends icms_data_page_Handler)
   • Related handler locations and purposes
   • Database table structure

4. Practical Examples - Provide code examples showing:

   • How to fetch symlink data using handlers
   • How to check symlink status and validity
   • How to create a basic routing layer on top of symlinks
   • Best practices for security and validation

5. Building a Custom Routing System - Step-by-step guide on:

   • Intercepting requests to check for symlink matches
   • Using page_moduleid and page_status fields for routing logic
   • Extending core handlers for advanced functionality
   • Fallback to default ImpressCMS routing

6. Debugging and Experimentation - Explain how to:

   • Test symlinks via the admin interface
   • Inspect the icmspage database table
   • Write custom modules that leverage symlinks
   • Debug routing issues

7. Security Considerations - Important notes on:

   • Input validation and sanitization
   • Output encoding
   • Permission checks
   • Status verification before routing

8. Real-world Use Cases - Examples of how symlinks enable:

   • SEO-friendly URL mapping
   • Block positioning by URL
   • Module-specific page routing
   • Centralized URL management

The document should be beginner-friendly, include actual code examples from the ImpressCMS codebase, and provide clear explanations for someone new to the framework. Include references to the actual file locations in the codebase.

This pull request was created as a result of the following prompt from Copilot chat.

Create comprehensive documentation explaining how symlinks work in ImpressCMS core and how they can be used to construct a routing system. This guide should be written for junior PHP developers with the goal of using the existing symlink functionality in ImpressCMS to build custom routing solutions.

The documentation should cover:

1. What are Symlinks in ImpressCMS? - Explain that symlinks are database records (not Unix system links) that map human-friendly URLs to specific modules/pages

2. How Symlinks Work - Describe the symlink lifecycle:

   • Symlink records stored in the icmspage database table
   • Key fields: page_id, page_title, page_url, page_status, page_moduleid
   • Where they're managed (System Module > Symlink Manager)
   • How routing logic interacts with them

3. Key Classes and Files - Document:

   • SystemPages class (extends icms_data_page_Object)
   • SystemPagesHandler class (extends icms_data_page_Handler)
   • Related handler locations and purposes
   • Database table structure

4. Practical Examples - Provide code examples showing:

   • How to fetch symlink data using handlers
   • How to check symlink status and validity
   • How to create a basic routing layer on top of symlinks
   • Best practices for security and validation

5. Building a Custom Routing System - Step-by-step guide on:

   • Intercepting requests to check for symlink matches
   • Using page_moduleid and page_status fields for routing logic
   • Extending core handlers for advanced functionality
   • Fallback to default ImpressCMS routing

6. Debugging and Experimentation - Explain how to:

   • Test symlinks via the admin interface
   • Inspect the icmspage database table
   • Write custom modules that leverage symlinks
   • Debug routing issues

7. Security Considerations - Important notes on:

   • Input validation and sanitization
   • Output encoding
   • Permission checks
   • Status verification before routing

8. Real-world Use Cases - Examples of how symlinks enable:

   • SEO-friendly URL mapping
   • Block positioning by URL
   • Module-specific page routing
   • Centralized URL management

The document should be beginner-friendly, include actual code examples from the ImpressCMS codebase, and provide clear explanations for someone new to the framework. Include references to the actual file locations in the codebase.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[skenow]

symlinks originally served the purpose of being able to define and select specific pages to place blocks, and set landing pages for groups after they log in. I hadn't thought of this as a routing mechanism.