PHPackages                             valksor/php-dev - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. valksor/php-dev

ActiveLibrary[Utility & Helpers](/categories/utility)

valksor/php-dev
===============

Development tools and utilities for PHP projects including build automation, file watching, and custom PHP-CS-Fixer rules

03PHPCI passing

Since Jan 24Pushed 3mo agoCompare

[ Source](https://github.com/valksor/php-dev)[ Packagist](https://packagist.org/packages/valksor/php-dev)[ RSS](/packages/valksor-php-dev/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Valksor PHP Dev
===============

[](#valksor-php-dev)

[![valksor](https://camo.githubusercontent.com/2af5a6a7e5f7da47cd0a924c8b00038f208f45f9b0d5be8d7a497a9808168187/68747470733a2f2f62616467656e2e6e65742f7374617469632f6f72672f76616c6b736f722f677265656e)](https://github.com/valksor)[![BSD-3-Clause](https://camo.githubusercontent.com/72547f8afb6b5ace804caebbf95c3bcbfc027ce9214777bc452f308f3165db01/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4253442d2d332d2d436c617573652d677265656e3f7374796c653d666c6174)](https://github.com/valksor/php-dev/blob/master/LICENSE)[![Coverage Status](https://camo.githubusercontent.com/a3f2b0724831c02e74c451dd140bd3d161cdcd0ce8958275f23f29832db6850e/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f76616c6b736f722f7068702d6465762f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/valksor/php-dev?branch=master)[![php](https://camo.githubusercontent.com/77da2f7bbc049873edb2d1045a756d7a32e3ba50440a8e0e76a9109f62f0771b/68747470733a2f2f62616467656e2e6e65742f7374617469632f7068702f2533453d382e342f707572706c65)](https://www.php.net/releases/8.4/en.php)

This repository contains these:
-------------------------------

[](#this-repository-contains-these)

RepositoryCoverageRepositoryCoverage[php-dev-build](https://github.com/valksor/php-dev-build)[![Coverage](https://camo.githubusercontent.com/5dd842851fda184e43f8b71e5b8316bb97a6e9499ac51d0be25a289e712d1cd6/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f76616c6b736f722f7068702d6465762d6275696c642f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/valksor/php-dev-build?branch=master)[php-dev-cs-fixer-custom-fixers](https://github.com/valksor/php-dev-cs-fixer-custom-fixers)[![Coverage](https://camo.githubusercontent.com/08ae29ed7ea4b6ba1bbceaec2ee0ed48ba2d42c0c814cbec028a59a3f049ba05/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f76616c6b736f722f7068702d6465762d63732d66697865722d637573746f6d2d6669786572732f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/valksor/php-dev-cs-fixer-custom-fixers?branch=master)[php-dev-snapshot](https://github.com/valksor/php-dev-snapshot)[![Coverage](https://camo.githubusercontent.com/2a96306192d5add06c44689cb9ac52e7c0201391a7310d0d111c31027c056aef/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f76616c6b736f722f7068702d6465762d736e617073686f742f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/valksor/php-dev-snapshot?branch=master)Modern development toolkit for Symfony applications that provides hot reloading, asset compilation, and automated build tools to speed up your development workflow.

Why Use Valksor Dev?
--------------------

[](#why-use-valksor-dev)

**Save Time**: Automatic browser reload when you change files - no more manual refreshing **Modern Tooling**: Integrated Tailwind CSS, ESBuild, and import map management **Zero Configuration**: Works out of the box with sensible defaults **Developer Experience**: Lightweight dev mode for quick feedback, full mode for comprehensive development **Production Ready**: Optimized asset building for deployment

Quick Start
-----------

[](#quick-start)

Install the package:

```
composer require valksor/php-dev

```

Enable the bundle in your Symfony application:

```
// config/bundles.php
return [
    Valksor\Bundle\ValksorBundle::class => ['all' => true],
];

```

Start development:

```
# Lightweight development (hot reload + SSE)
php bin/console valksor:dev

# Full development environment (all services)
php bin/console valksor:watch

# Build production assets
php bin/console valksor-prod:build

```

Basic Configuration
-------------------

[](#basic-configuration)

For most projects, the simple configuration is all you need:

```
# config/packages/valksor.yaml
valksor:
    build:
        enabled: true
        hot_reload:
            enabled: true
        tailwind:
            enabled: true
        importmap:
            enabled: true

```

### When to Use Simple Configuration

[](#when-to-use-simple-configuration)

Use the basic setup above when:

- **Standard Symfony project** with single app structure
- **Default locations** for assets (`assets/`, `templates/`, `src/`)
- **Beginning development** and want to get started quickly
- **Most common use cases** - hot reload, Tailwind CSS, and import maps

### When to Use Advanced Configuration

[](#when-to-use-advanced-configuration)

Switch to advanced service configuration only when you need:

```
# config/packages/valksor.yaml
valksor:
    build:
        services:
            binaries:
                enabled: true
                flags: ["init", "dev", "prod"]
                options:
                    required: ["tailwindcss", "esbuild", "daisyui"]
            hot_reload:
                enabled: true
                flags: ["dev"]
                options:
                    debounce_delay: 0.3
                    watch_dirs: ["/src", "/templates"]
            tailwind:
                enabled: true
                flags: ["dev", "prod"]
                options:
                    minify: false # Auto-sets to true in prod

```

**Use advanced configuration when:**

- **Multi-app projects** with separate `apps/` directory
- **Custom file locations** for assets or templates
- **Specific performance tuning** (debounce delays, watch directories)
- **Selective service execution** (disable certain features)
- **Production optimization** (different settings per environment)

That's it! Valksor Dev will automatically:

- Watch your PHP, Twig, CSS, and JavaScript files
- Reload your browser when files change
- Compile Tailwind CSS automatically
- Manage JavaScript import maps
- Download necessary build tools

Frontend Integration
--------------------

[](#frontend-integration)

### Browser Hot Reload Setup

[](#browser-hot-reload-setup)

To enable automatic browser reloading, add this to your base HTML template:

```
{# templates/base.html.twig #}

    {% block title %}My App{% endblock %}

    {{ valksor_sse_importmap_definition(['head', 'app']) }}
    {{ valksor_sse_importmap_scripts(['head']) }}

{% block body %}{% endblock %}
{% block javascripts %}
    {{ valksor_sse_importmap_scripts(['app']) }}
    {{ include('@ValksorSse/sse.html.twig') }}
{% endblock %}

```

**What each part does:**

- `valksor_sse_importmap_definition()`: Sets up the import map and SSE connection
- `valksor_sse_importmap_scripts()`: Loads JavaScript modules for specific app sections
- `@ValksorSse/sse.html.twig`: Includes the SSE client that handles browser reloads

### Asset File Setup

[](#asset-file-setup)

Create your frontend files in these locations:

```
# CSS files (automatically compiled by Tailwind)
assets/styles/app.css

# JavaScript files (managed by import map system)
assets/js/app.js

# Twig templates (auto-reload on changes)
templates/base.html.twig
templates/index.html.twig

# Compiled assets (automatically generated)
public/styles/app.css

```

### Tailwind CSS Setup

[](#tailwind-css-setup)

1. Create your main CSS file:

```
/* assets/styles/app.css */
@import "tailwindcss" source(none);
@source "../templates/**/*.html.twig";
@source "../js/*.js";

@theme {
    --color-primary: #3b82f6;
}

@utility "theme-switcher" {
    /* Custom utilities if needed */
}

```

2. The compiled CSS will be automatically available at `/styles/app.css`

### JavaScript Import Maps

[](#javascript-import-maps)

Your JavaScript automatically gets import map support:

```
// assets/js/app.js
import { hotwire } from "@hotwired/turbo";
import { stimulus } from "@hotwired/stimulus";

// These imports are automatically resolved by the import map system
// No need for manual script tags or complex bundling setup

```

Commands
--------

[](#commands)

CommandWhat It DoesWhen to Use`valksor:dev`Lightweight dev mode (hot reload + SSE)Quick frontend development`valksor:watch`Full dev environment (all services)Complete development workflow`valksor-prod:build`Build production assetsBefore deployment`valksor:tailwind`Build Tailwind CSS onlyManual CSS compilation`valksor:importmap`Update import maps onlyManual JavaScript updates`valksor:binary`Download build toolsSetup or update tools`valksor:icons`Generate SVG iconsWhen using icon system`valksor:hot-reload`Hot reload service onlyCustom reload setups`valksor:binaries:install`Install all binariesFresh environment setup### Command Options

[](#command-options)

All commands support these useful options:

```
# Run on specific app (multi-app projects)
php bin/console valksor:watch --id=www

# Non-interactive mode (for CI/automated scripts)
php bin/console valksor:watch --non-interactive

# Specify environment
php bin/console valksor:dev --env=prod

```

What's Included?
----------------

[](#whats-included)

This meta-package automatically includes:

- **valksor/php-dev-build** - Build tools, hot reloading, and asset management
- **valksor/php-dev-cs-fixer-custom-fixers** - Enhanced code quality fixers

### Build Tools Features

[](#build-tools-features)

- **Hot Reloading**: Automatic browser refresh on file changes
- **Tailwind CSS**: Integrated compilation with DaisyUI support
- **Import Maps**: Modern JavaScript dependency management
- **Binary Management**: Automatic tool downloads (ESBuild, Tailwind CSS)
- **Icon Generation**: SVG icon processing with Lucide integration

### Code Quality Features

[](#code-quality-features)

- **PHP 8.4+ Best Practices**: Modern coding standards
- **Promoted Constructor Properties**: Automatic refactoring
- **Doctrine Migration Cleanup**: Remove auto-generated comments
- **Custom Fixers**: Additional rules beyond PSR-12

Development Workflow
--------------------

[](#development-workflow)

### Daily Development

[](#daily-development)

```
# Start your day
php bin/console valksor:watch

# Work on your files - changes trigger automatic reloads
# Edit templates → browser reloads
# Edit CSS → Tailwind compiles → browser reloads
# Edit PHP → browser reloads

```

### Before Deployment

[](#before-deployment)

```
# Build optimized assets
php bin/console valksor-prod:build

```

Multi-App Projects
------------------

[](#multi-app-projects)

For projects with multiple applications, you need to configure the project structure and use app IDs.

### Project Structure Setup

[](#project-structure-setup)

Organize your multi-app project like this:

```
your-project/
├── apps/
│   ├── www/                    # Main website
│   │   ├── assets/
│   │   │   ├── js/
│   │   │   └── styles/
│   │   └── templates/
│   ├── admin/                  # Admin interface
│   │   ├── assets/
│   │   └── templates/
│   └── api/                    # API application
│       └── templates/
├── infrastructure/              # Shared components
│   ├── src/
│   └── templates/
└── config/
    └── packages/
        └── valksor.yaml

```

### Multi-App Configuration

[](#multi-app-configuration)

```
# config/packages/valksor.yaml
valksor:
    build:
        enabled: true
        project:
            apps_dir: "apps" # Directory containing apps
            infrastructure_dir: "infrastructure" # Shared code
        hot_reload:
            enabled: true
        tailwind:
            enabled: true
        importmap:
            enabled: true

```

### Using App IDs

[](#using-app-ids)

Each app directory name becomes an app ID you can use with commands:

```
# Run on all apps (default)
php bin/console valksor:watch

# Run on specific app only
php bin/console valksor:watch --id=www       # Watch only apps/www/
php bin/console valksor:watch --id=admin     # Watch only apps/admin/
php bin/console valksor:watch --id=api       # Watch only apps/api/

# Build assets for specific app
php bin/console valksor-prod:build --id=www

# Generate icons for specific app
php bin/console valksor:icons --id=admin

```

### Multi-App Frontend Integration

[](#multi-app-frontend-integration)

For multi-app projects, include the app ID in your templates:

```
{# apps/www/templates/base.html.twig #}

    {% block title %}Website{% endblock %}

    {{ valksor_sse_importmap_definition(['infrastructure/head', 'www/head']) }}
    {{ valksor_sse_importmap_scripts(['infrastructure/head', 'www/head']) }}

{% block body %}{% endblock %}
{% block javascripts %}
    {{ valksor_sse_importmap_scripts(['infrastructure/app', 'www/app']) }}
    {{ include('@ValksorSse/sse.html.twig') }}
{% endblock %}

```

**Key points:**

- Use `{{ asset(app_id ~ '/styles/app.css') }}` for app-specific CSS
- Include app ID in import map arrays: `['infrastructure/head', 'www/head']`
- Each app gets its own hot reload and asset compilation

Requirements
------------

[](#requirements)

- **PHP 8.4 or higher**
- **inotify extension** (for file watching)
- **PCNTL extension** (for process management)
- **POSIX extension**
- **friendsofphp/php-cs-fixer** (3.81.0 or higher)
- **symfony/framework-bundle** (7.2.0 or higher)
- **Valksor Bundle** and related components

Platform Requirements
---------------------

[](#platform-requirements)

⚠️ **Linux Only Required**

The Valksor PHP Dev toolkit requires **Linux** due to its dependency on the **inotify** extension for efficient file system monitoring.

- **inotify** is a Linux kernel subsystem available only on Linux platforms
- File watching is essential for the hot reload, asset compilation, and development workflow features
- These tools are not compatible with Windows or macOS
- Docker containers can provide a Linux environment on other platforms

Project Structure
-----------------

[](#project-structure)

### Standard Single-App Setup

[](#standard-single-app-setup)

For most Symfony projects, use the standard structure:

```
your-project/
├── assets/
│   ├── js/
│   │   └── app.js
│   └── styles/
│       └── app.css
├── templates/
│   ├── base.html.twig
│   └── index.html.twig
├── src/
│   └── Controller/
├── public/
│   └── styles/          # Compiled CSS (auto-generated)
├── config/
│   └── packages/
│       └── valksor.yaml
└── bin/
    └── console

```

### Multi-App Setup

[](#multi-app-setup)

For complex projects with multiple applications:

```
your-project/
├── apps/
│   ├── www/
│   │   ├── assets/
│   │   └── templates/
│   └── admin/
│       ├── assets/
│       └── templates/
├── infrastructure/          # Shared code
│   ├── src/
│   └── templates/
├── config/
│   └── packages/
│       └── valksor.yaml
└── bin/
    └── console

```

### What Gets Auto-Discovered

[](#what-gets-auto-discovered)

Valksor Dev automatically finds and processes:

- **Tailwind CSS files**: `*.tailwind.css`, `assets/styles/*.css`
- **JavaScript files**: `assets/js/*.js`, `apps/*/assets/js/*.js`
- **Templates**: `templates/**/*.html.twig`, `apps/*/templates/**/*.html.twig`
- **Icons**: `assets/icons/*.svg`, `assets/icons/**/*.svg`

### First Run - What to Expect

[](#first-run---what-to-expect)

When you first run `valksor:watch`:

1. **Binary Downloads**: ESBuild, Tailwind CSS, and other tools are downloaded automatically
2. **Asset Discovery**: Valksor scans your project for CSS, JS, and template files
3. **Initial Compilation**: CSS is compiled and import maps are generated
4. **Server Start**: Hot reload server starts on port 8080

You should see output like:

```
[Valksor] Downloading build tools...
[Valksor] Scanning for assets...
[Valksor] Starting hot reload server on port 8080
[Valksor] Watching for file changes...

```

### Common Setup Issues

[](#common-setup-issues)

**Permission errors on binary downloads:**

```
# Fix binary directory permissions
chmod +x bin/build-tools/*

```

**Inotify limits (Linux):**

```
# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase limit if needed
echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

```

**Port 8080 already in use:**

```
# Check what's using the port
lsof -i :8080

# Kill existing processes
pkill -f valksor

```

Documentation
-------------

[](#documentation)

- **[Build Tools Guide](src/ValksorDev/Build/README.md)** - Detailed configuration and workflow
- **[Custom Fixers Guide](src/ValksorDev/PhpCsFixerCustomFixers/README.md)** - All available code quality fixers

Support
-------

[](#support)

- **Documentation**: [Full documentation](https://github.com/valksor/php-dev)
- **Issues**: [GitHub Issues](https://github.com/valksor/php-dev/issues) for bug reports and feature requests
- **Discussions**: [GitHub Discussions](https://github.com/orgs/valksor/discussions/categories/php-dev) for questions and community support

License
-------

[](#license)

This package is licensed under the [BSD-3-Clause License](LICENSE).

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance53

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/c4db85e32518c5a6caa2fd625032a2b016ef42d60cf8a101c165cc5c0048b221?d=identicon)[k0d3r1s](/maintainers/k0d3r1s)

---

Top Contributors

[![k0d3r1s](https://avatars.githubusercontent.com/u/38725938?v=4)](https://github.com/k0d3r1s "k0d3r1s (91 commits)")

### Embed Badge

![Health badge](/badges/valksor-php-dev/health.svg)

```
[![Health](https://phpackages.com/badges/valksor-php-dev/health.svg)](https://phpackages.com/packages/valksor-php-dev)
```

###  Alternatives

[carlcs/craft-redactorcustomstyles

Redactor Custom Styles plugin for Craft CMS

59221.7k3](/packages/carlcs-craft-redactorcustomstyles)[apinstein/expiring-hash

A utililty to easily create crypographically signed URLs for temporary ad-hoc URL access.

1634.4k1](/packages/apinstein-expiring-hash)[serkanalgur/cmb2-field-faiconselect

Font Awesome icon selector for powerful custom metabox generator CMB2

202.2k](/packages/serkanalgur-cmb2-field-faiconselect)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)