Repository navigation
Quick Start
mouse-php is a PHP framework that aims to provide a simple and easy-to-use and understand API for building web applications, while also providing PHP developers with modern tooling and developer experience. mouse-php consists mainly of two major components:
- The core framework: This is the actual web application framework that you will build your application inside, and if you deploy with mouse-php will be packaged to your CGI of choice.
- squeak Shell: Squeak is the companion dev-tool included with mouse-php. It is designed to provide a powerful and intuitive development environment for PHP developers. It provides bootstrapping for new applications, scaffolding for framework components, middleware management, and much more. One of the key features of squeak is the development server that provides hot realoading of a page as changes are made to it. Similar to Vite, or other modern bundlers for JavaScript.
We built mouse-php to be weakly opinionated and highly transparent. It comes out of the box with a clear, organized way to build your application, assuming certain tools and structures. However, we believe in keeping the mechanics visible. Because the framework doesn't obfuscate its inner workings, any developer with a solid grasp of PHP can easily step off the golden path and customize the architecture. It guides you when you want it to, and gets out of your way when you don't.
Before creating your first mouse-php application, you will need to make sure your machine has the following depenencies:
- PHP 8.0+
- Curl
-
Extensions:
PDO,SQLite3,php-sqlite3,php-pdo-sqlite,php-pdo-mysql - Database: MariaDB or Mysql
- Web Server: A CGI-compatible web server like Apache or NGINX (Recommended for production, not required for local development)
Once you have all the dependencies installed,you have enabled the required extensions, and you have a database running you must then create a database for your application.
- Install and configure your preferred database server (MariaDB/MySQL).
- Create a dedicated database and user for your application.
- Retain these credentials for the configuration wizard when you run
squeak init.
Now that you have all the prerequisites installed and set up you can start building your first application.There are two ways to get started:
Before bootstrapping a project, ensure Composer is installed globally on your system and that its global binary directory is present in your shell PATH.
If you do not already have Composer installed globally, run the installer script to place the binary into /usr/local/bin:
# Download and execute the official Composer installer
curl -sS https://getcomposer.org/installer | php
# Move the executable to your global path
sudo mv composer.phar /usr/local/bin/composerNext, ensure Composer's global vendor binary directory is added to your environment PATH (typically ~/.config/composer/vendor/bin on Linux or ~/.composer/vendor/bin):
# Add this line to your ~/.bashrc or ~/.zshrc file:
export PATH="$(composer config -g home)/vendor/bin:$PATH"
# Apply the changes
source ~/.bashrcInstall the CLI tool globally using Composer:
composer global require mouse-php/create-mouse-appRun create-mouse-app followed by your desired project directory name. This command leverages Squeak's initialization engine to scaffold your directory structure, create an .env file, and generate authentication code if your database configuration is set up:
create-mouse-app my-appOnce the scaffolding script finishes running, move into your new project directory and launch the local development server. Launch the squeak CLI Shell to bootstrap your project:
php squeakStart the hot-reloading development server by running the following command inside the squeak shell:
> serveYou will be prompted to select your .env configuration, target host, and port. Once active, navigate to your configured address (e.g. http://localhost:9000).
If you see the default welcome page shown below, you are ready to start developing!
Clone the repository directly then cd into the directory:
git clone https://github.com/drawfig/mouse-php.git
cd mouse-phpOr if you want to name your project something else:
git clone https://github.com/drawfig/mouse-php.git my-project
cd my-project`Alternatively, you can download the latest release from the releases page.
Launch the squeak CLI Shell to bootstrap your project:
php squeakInside the interactive squeak shell, run the initialization command (Note: This is where you will enter your database credentials):
> initThe init command begins by cleaning up the project directory and installing composer. It then runs the .env file generation wizards that will walk you through setting up your application. This includes creating the first application configuration file, the database configuration file, and the deployment configuration file.
You will also be asked if you want to run the authentication scaffolding. If choose to run this, squeak will automatically add the controllers, and models to create and authenticate users. As well as creating the users table in the database you created for the project.
Once the initialization wizard is complete, you now have a fully functional application that you can start developing on and are ready to start the server.
Start the hot-reloading development server by running the following command inside the squeak shell:
> serveYou will be prompted to select your .env configuration, target host, and port. Once active, navigate to your configured address (e.g. http://localhost:9000).
If you see the default welcome page shown below, you are ready to start developing!
If you have any questions or need help, reach out to us on our Discord server or GitHub Discussions.
While mouse-php accepts standard raw JSON over HTTP/WebSockets, the recommended JavaScript client driver is coby-jack. It handles mRPC HMAC signing, token storage, and session refresh loops out of the box. See Client Ecosystem & Integration.