DotApper CLI Tool

Home

Welcome to the DotApper CLI, the official command-line interface for the dotApp PHP Framework. DotApper is designed to streamline your development workflow, making it easy to set up, manage, and extend your dotApp projects with a simple and powerful set of commands.

What is DotApper CLI?

DotApper CLI is a lightweight utility that helps you:

• Install and update the dotApp PHP Framework.
• Create and manage modules, controllers, middleware, and models.
• Generate and optimize project assets like routes and .htaccess files.
• Boost productivity with an intuitive command-line interface.

Built with simplicity and efficiency in mind, DotApper CLI is perfect for developers who want to focus on building modern web applications without getting bogged down by repetitive setup tasks.

Why Use DotApper CLI?

• Fast Setup: Install dotApp in seconds with a single command.
• Modular Workflow: Easily create and organize modules for scalable projects.
• Developer-Friendly: Clear commands and helpful outputs save time.
• Seamless Integration: Works hand-in-hand with the dotApp framework's modular architecture.

Get Started

Ready to dive in? Head over to the Installation section to set up DotApper CLI and start your first project. Or, explore the Commands section to discover the full range of tools at your disposal.

Quick Start Example:

# Install dotApp with DotApper CLI
php dotapper.php --install
        

For more details, check out the full dotApp Documentation or reach out to our Support team.

Proudly made in Slovakia 🇸🇰

Installation

Installing the DotApper CLI is simple and requires only downloading a single file, dotapper.php, to your local machine. This section explains how to obtain and prepare the DotApper CLI for use.

Prerequisites

Before installing DotApper CLI, ensure your environment meets the following requirement:

• PHP: Version 7.4 or higher, with command-line access to run PHP scripts.

Installing DotApper CLI

To install DotApper CLI, follow these steps to download the dotapper.php file:

1. Open your web browser and navigate to the following link: https://github.com/dotsystems-sk/DotApp/raw/refs/heads/main/dotapper.php.
2. The browser will display the source code of dotapper.php. Right-click anywhere on the page and select Save Page As (or similar, depending on your browser).
3. Save the file as dotapper.php to your desired directory (e.g., your project folder or a tools directory).
4. Verify that the file is saved correctly by opening a terminal and running:

   
   php dotapper.php --help
               

   This should display a list of available DotApper CLI commands, confirming that the tool is ready to use.

Notes

• File Placement: You can place dotapper.php in any directory, but it’s typically stored in your project root for easy access.
• Execution: Run DotApper CLI commands using php dotapper.php [command] from the directory containing the file.
• Next Steps: Learn how to use DotApper CLI to manage dotApp projects in the Commands section.
• Troubleshooting: If the --help command fails, ensure PHP 7.4+ is installed and accessible in your terminal. Check the FAQ for common issues.

With dotapper.php downloaded, you’re ready to explore its commands. Visit the Commands section to start using DotApper CLI.

Commands

The DotApper CLI provides a powerful set of commands to streamline development with the dotApp PHP Framework. This section details all available commands, their purposes, and how to use them. Commands are executed in the terminal using the dotapper.php script from the directory where it is located.

Command Structure

All DotApper CLI commands follow this format:

php dotapper.php [command]
    

Replace [command] with the specific command and its parameters as described below. To see a list of all commands, run:

php dotapper.php --help
    

Available Commands

The following commands are available in DotApper CLI, each designed to simplify tasks such as installing the framework, managing modules, and inspecting routes.

--help

Displays a list of all available commands and their descriptions.

Example:

php dotapper.php --help
    

Result: Outputs a help menu with all commands, e.g., --install, --create-module, etc.

--install

Installs a fresh copy of the dotApp PHP Framework in the current directory, creating its directory structure and configuration files.

Example:

php dotapper.php --install
    

Result: Sets up the dotApp framework, including directories like app/, public/, and the app/config.php file.

--update

Updates the dotApp framework to the latest version while preserving existing configuration files and modules.

Example:

php dotapper.php --update
    

Result: Downloads and applies the latest dotApp core files, keeping app/config.php and module directories intact.

--create-module=

Creates a new module with the specified name, initializing its directory structure for controllers, middleware, and models.

Example:

php dotapper.php --create-module=Blog
    

Result: Creates a Blog module in app/modules/Blog/ with subdirectories for components.

--modules

Lists all modules currently available in the dotApp project.

Example:

php dotapper.php --modules
    

Result: Outputs a list of module names, e.g., Blog, Auth, Shop.

--module= --create-controller=

Creates a new controller in the specified module.

Example:

php dotapper.php --module=Blog --create-controller=ArticleController
    

Result: Generates ArticleController.php in app/modules/Blog/controllers/.

--module= --create-middleware=

Creates a new middleware in the specified module.

Example:

php dotapper.php --module=Blog --create-middleware=AuthMiddleware
    

Result: Generates AuthMiddleware.php in app/modules/Blog/middleware/.

--module= --create-model=

Creates a new model in the specified module.

Example:

php dotapper.php --module=Blog --create-model=PostModel
    

Result: Generates PostModel.php in app/modules/Blog/models/.

--list-routes

Lists all defined routes in the dotApp application, including their HTTP methods, paths, associated controllers, and middleware (before and after hooks).

Example:

php dotapper.php --list-routes
    

Result: Outputs a detailed list of routes.

Use Case: Useful for debugging routing issues or documenting the application’s routing structure.

--list-route=

Displays all routes that match the specified path, including their HTTP methods, associated controllers, and middleware (before and after hooks). The path can be exact (e.g., / for the homepage) or partial (e.g., /documentation/).

Example 1: Homepage Routes

php dotapper.php --list-route=/
    

Result: Outputs routes matching /.

Example 2: Documentation Routes

php dotapper.php --list-route=/documentation/
    

Result: Outputs routes matching /documentation/.

Use Case: Helps identify which controllers and middleware are triggered for a specific URL, aiding in debugging or route optimization.

--create-htaccess

Creates or recreates a .htaccess file in the public/ directory to configure URL rewriting for Apache servers.

Example:

php dotapper.php --create-htaccess
    

Result: Generates a .htaccess file optimized for dotApp's routing.

--optimize-modules

Optimizes module loading for projects with many modules, improving performance by caching module metadata.

Example:

php dotapper.php --optimize-modules
    

Result: Creates or updates a module cache to reduce loading time.

Command Summary

The table below provides a quick reference for all DotApper CLI commands:

Notes

• Ensure you run commands from the directory containing dotapper.php.
• Commands like --install, --create-module, and --list-routes require a valid dotApp project structure in the current directory.
• For practical examples of using these commands, see the Usage section.
• If a command fails, refer to the FAQ or contact Support.

To see these commands in action, check out the Usage section for real-world examples.

Advanced

The DotApper CLI offers advanced features for developers who want to automate workflows, script complex tasks, or extend its functionality for custom needs in dotApp PHP Framework projects. This section explores scripting, automation, combining commands, and tips for extending DotApper CLI.

Scripting with DotApper CLI

You can combine multiple DotApper CLI commands in shell scripts (e.g., Bash or PowerShell) to automate repetitive tasks, such as setting up a new project with predefined modules and configurations.

Example: Bash Script for Project Setup

#!/bin/bash
# setup_project.sh

echo "Setting up new dotApp project..."
php dotapper.php --install
php dotapper.php --create-module=Blog
php dotapper.php --module=Blog --create-controller=ArticleController
php dotapper.php --module=Blog --create-middleware=AuthMiddleware
php dotapper.php --module=Blog --create-model=PostModel
php dotapper.php --create-htaccess
echo "Project setup complete!"
    

Usage: Save the script as setup_project.sh, make it executable (chmod +x setup_project.sh), and run it:

./setup_project.sh
    

Result: Installs dotApp, creates a Blog module with a controller, middleware, and model, and generates a .htaccess file.

FAQ

This section addresses frequently asked questions about the DotApper CLI tool for the dotApp PHP Framework. It covers common issues, troubleshooting steps, and clarifications to help you use DotApper CLI effectively.

1. Why do I get a "command not found" error when running php dotapper.php?

This error typically occurs if PHP is not installed, not accessible in your terminal, or if dotapper.php is not in the current directory.

Solution:

• Verify PHP is installed and meets the minimum version requirement (7.4+):

  
  php --version
              

  If PHP is not installed, download it from php.net.
• Ensure you’re in the directory containing dotapper.php. Check with:

  
  ls | grep dotapper.php
              

  If missing, download it as described in the Installation section.
• Add PHP to your system’s PATH if it’s installed but not accessible. For example, on Linux:

  
  export PATH=$PATH:/path/to/php
              

2. Why does --install fail with a permissions error?

The --install command requires write permissions in the current directory to create the dotApp framework’s files and directories.

Solution:

• Check directory permissions:

  
  ls -ld .
              

  Ensure your user has write access.
• Grant write permissions:

  
  chmod -R u+w .
              

• Alternatively, run the command with elevated privileges (use cautiously):

  
  sudo php dotapper.php --install
              

3. What should I do if --list-routes shows no routes?

If --list-routes or --list-route= returns an empty list, your dotApp project may not have defined routes or the project structure may be incomplete.

Solution:

• Ensure the dotApp framework is installed:

  
  php dotapper.php --install
              

• Verify that routes are defined in your controllers or routing files. For example:

  
  Router::get('/home', 'HomeController@index');
              

• Check for errors in the project directory by running:

  
  php dotapper.php --list-routes
              

  If errors persist, ensure the app/config.php file exists and is valid.

4. Can I use DotApper CLI without installing dotApp?

Some commands (e.g., --help, --install) work without a dotApp project, but most commands (e.g., --update, --create-module, --list-routes) require a dotApp project structure in the current directory.

Solution:

• Run --install to set up a dotApp project:

  
  php dotapper.php --install
              

• Alternatively, use --help to explore commands without a project:

  
  php dotapper.php --help
              

5. Why does --update overwrite my custom files?

The --update command is designed to preserve app/config.php and module directories, but it may overwrite core framework files. Custom changes to core files will be lost.

Solution:

• Back up your project before running --update:

  
  cp -r . /path/to/backup
              

• Avoid modifying core framework files. Instead, use modules for custom functionality (see Usage).
• If custom files were overwritten, restore from your backup and reapply changes in a module.

6. How do I debug issues with --list-route=?

If --list-route= doesn’t return the expected routes, controllers, or middleware, the route may not be registered, or there may be an issue with the path format.

Solution:

• Ensure the path is correct, including leading/trailing slashes (e.g., / or /documentation/).
• Run --list-routes to view all routes and confirm the target path exists:

  
  php dotapper.php --list-routes
              

• Check your routing definitions in controllers or routing files for errors.
• If middleware or controllers are missing, verify they are correctly registered in the module’s configuration.

7. Can I run DotApper CLI commands globally?

DotApper CLI is designed to run from the project directory containing dotapper.php, but you can make it globally accessible by adding it to your system’s PATH.

Solution:

• Move dotapper.php to a directory in your PATH (e.g., /usr/local/bin/ on Linux):

  
  sudo mv dotapper.php /usr/local/bin/dotapper
  sudo chmod +x /usr/local/bin/dotapper
              

• Run commands globally from any directory:

  
  php dotapper --help
              

• Note: You still need to be in a dotApp project directory for most commands to work.

8. What if a command fails without a clear error message?

Some failures may result from PHP configuration, file permissions, or an incomplete dotApp setup.

Solution:

• Enable verbose PHP errors by adding this to dotapper.php (temporarily):

  
  ini_set('display_errors', 1);
  ini_set('display_startup_errors', 1);
  error_reporting(E_ALL);
              

• Check PHP logs for detailed errors (location depends on your server configuration).
• Ensure all prerequisites are met (see Installation).