0.4.1 2024-03-27 19:16 UTC

This package is auto-updated.

Last update: 2024-04-27 19:20:23 UTC


Catpaw is an opinionated group of libraries centered around catpaw/core, which is a dependency injection library built for amphp that makes heavy use of php attributes.

Table of Contents

Topic Implemented Repository Read
🌐 Web Route Handlers catpaw-web Read
🌐 Web Route Controllers catpaw-web Read
🌐 Web Path Parameters catpaw-web Read
🌐 Web Path Not Found catpaw-web Read
🌐 Web Session catpaw-web Read
🌐 Open API catpaw-web Read
🌐 File System Web Routes catpaw-web Read
⚡ Entry catpaw-core Read
🌐 Web Byte Range Requests catpaw-web Read
⚡ Custom Attributes catpaw-core Read
🌐 Web Filters catpaw-web Read
🌐 Web Sockets catpaw-web Read
💡 RaspberryPI catpaw-raspberrypi Read
⚡ Services catpaw-core Read
🗄 MySQL Repositories catpaw-mysql TODO
⚡ Stores catpaw-store Read
⚡ Dev Tools Binary Download catpaw-dev-tools Read
⚡ Queues catpaw-queue Read
💡 Text catpaw-text TODO
💡 Schedule catpaw-schedule TODO
💡 SDL catpaw-libsdl Read


Type Implemented Description Github Template Read
Blank using only the core library Template Read
Web create a web server Template Read
Markdown create a web server using Markdown Template TODO

Note use with composer

composer create-project catpaw/starter
composer create-project catpaw/web-starter
composer create-project catpaw/markdown-starter


This project is aimed at linux distributions, some features may or not may work on Windows or MacOS.
Feel free to contribute fixing issues for specific platforms.

Get started

In order to get started you will need php 8.1 or a more recent version.

All you need to do is create a new project using the starter template.

composer create-project catpaw/starter

Or you could also clone the template from

Every application must declare a main function in the global scope, that will be your entry point:

// src/main.php
function main(){
    echo "hello world\n";

After you've created your new project, you can run it using

composer watch

to watch file changes (useful in development) or

composer start

for production mode.

Build & Run

It is possible, but not required, to build your application into a single .phar file using

composer build

The building process can be configured inside the build.yml file.

After building your application, you can simply run it using

php dist/app.phar

The resulting .phar, by default (check build.yml), includes the following directories:

  • ./src
  • ./vendor
  • ./resources
  • ./bin
  • ./.build-cache (created at comptile time)

which means it's a portable binary, you just need to make sure php is installed on whatever machine you're trying to run it on.

A note on versioning

Given the versioning string major.minor.patch, all libraries that are compatible with eachother will always have the same major and minor versions.
Regardless if a library has actually had any major or minor changes, its version will be bumped to match all the other libraries to indicate that given library is compatible with the latest features.

The patch number may vary from library to library, but the major and minor numbers should all match.

For example, if you're using catpaw/core:^0.2 and you want to add catpaw/web to your project, you should always pick catpaw/web:^0.2 to match your core version.


I'm a single developer and this gives me more freedom to add features without breaking previous versions and I like to organize my projects this way.

Looking for some examples?

You can follow along with the examples provided by the catpaw/examples repository at

Debugging with VSCode

In order to debug with vscode you will need to configure both vscode and xdebug (3.x).

XDebug 3.x configuration for VSCode

In your php.ini file add:


VSCode configuration

Make new a ./.vscode/launch.json file in your project and add the following configuration if you don't have it already:

    "version": "0.2.0",
    "configurations": [
            "name": "Listen (paw)",
            "type": "php",
            "request": "launch",
            "port": 9003
            "name": "main (paw)",
            "type": "php",
            "request": "launch",
            "program": "${workspaceFolder}/bin/start",
            "cwd": "${workspaceFolder}",
            "args": [
            "runtimeArgs": [
            "env": {
                "XDEBUG_MODE": "debug",
                "XDEBUG_CONFIG": "client_port=${port}"

The first configuration will passively listen for xdebug, while the second one will launch the currently opened script.