Dev Tools

Developer-oriented utilities for theme creation and translation management.

Check Translations

The pteroca:dev:check-translations command is a developer-oriented tool designed to compare two YAML translation files and identify any missing keys in the target file. It is particularly useful in ensuring consistency between translation files during development.

• Command: pteroca:dev:check-translations

• Alias: app:show-missing-translations (deprecated, removed in v1.0.0)

Arguments

• mainFile (required): Main file to compare with

• compareFile (required): File to compare with the main file

Examples

# Recommended (v0.6+)
php bin/console pteroca:dev:check-translations \
  src/Core/Resources/translations/messages.en.yaml \
  src/Core/Resources/translations/messages.pl.yaml

# Deprecated (still works until v1.0.0)
php bin/console app:show-missing-translations \
  src/Core/Resources/translations/messages.en.yaml \
  src/Core/Resources/translations/messages.pl.yaml

Use Cases

Translation File Validation:

• Compare English (main) translation file with other language files

• Identify missing translation keys

• Ensure all translations are up to date

Example Workflow:

1. Update English translation file (messages.en.yaml)

2. Run comparison with other language files

3. Add missing keys to target language files

# Check Polish translations
php bin/console pteroca:dev:check-translations \
  src/Core/Resources/translations/messages.en.yaml \
  src/Core/Resources/translations/messages.pl.yaml

# Check German translations
php bin/console pteroca:dev:check-translations \
  src/Core/Resources/translations/messages.en.yaml \
  src/Core/Resources/translations/messages.de.yaml

Output

The command outputs:

• Missing keys in the target file

• Total count of missing translations

• Suggested keys to add

Make Theme

The pteroca:dev:make-theme command creates a new theme scaffold with interactive configuration.

• Command: pteroca:dev:make-theme

• Alias: make:theme (deprecated, removed in v1.0.0)

Examples

# Recommended (v0.6+)
php bin/console pteroca:dev:make-theme

# Deprecated (still works until v1.0.0)
php bin/console make:theme

Interactive Prompts

The command will interactively ask for:

Theme Configuration:

• Theme name - Kebab-case identifier (e.g., my-awesome-theme)

• Display name - Human-readable name (e.g., "My Awesome Theme")

• Description - Brief theme description

• Author - Your name or organization

• Author email - Contact email

• Version - Semantic version (default: 1.0.0)

• License - License identifier (default: MIT)

• PteroCA version compatibility - Minimum PteroCA version (default: 0.6.0)

What the Command Does

1. Copies default theme to themes/{your-theme-name}/

2. Creates template.json with your provided metadata

3. Copies assets to public/assets/theme/{your-theme-name}/

4. Sets up directory structure with all necessary folders

5. Makes theme ready for customization

Example Output

Theme Creator
=============

Creating a new theme based on the default PteroCA theme.

Theme name (kebab-case, e.g., my-awesome-theme):
> dark-professional

Display name:
> Dark Professional

Author name:
> John Doe

Author email:
> [email protected]

Description:
> A sleek dark theme for professional hosting panels

License [MIT]:
> MIT

Creating theme 'dark-professional'...
✓ Copied theme templates to themes/dark-professional/
✓ Copied theme assets to public/assets/theme/dark-professional/
✓ Created template.json with metadata
✓ Theme created successfully!

Next steps:
1. Go to Settings → Appearance → Current theme
2. Select 'Dark Professional'
3. Start customizing templates in themes/dark-professional/
4. Edit styles in public/assets/theme/dark-professional/css/

Next Steps After Creation

1. Activate Your Theme:

• Navigate to Settings → Appearance → Current theme

• Select your new theme

• Click Save

2. Start Customizing:

• Edit templates in themes/dark-professional/

• Modify styles in public/assets/theme/dark-professional/css/

• Add JavaScript in public/assets/theme/dark-professional/js/

3. Test Your Theme:

• Clear browser cache (Ctrl+Shift+R)

• Check all pages

• Test responsive design

Upgrade Theme

The pteroca:dev:upgrade-theme command upgrades legacy themes to support the new context-based system introduced in v0.6.3.

• Command: pteroca:dev:upgrade-theme

Arguments

• theme-name (optional): Name of the theme to upgrade (interactive selection if omitted)

Options

• --force, -f: Force upgrade without confirmation prompts

• --no-backup: Skip automatic backup before upgrade (DANGEROUS)

Examples

# Upgrade a theme with interactive confirmation
php bin/console pteroca:dev:upgrade-theme my-theme

# Force upgrade without prompts
php bin/console pteroca:dev:upgrade-theme my-theme --force

# Upgrade without creating backup (not recommended)
php bin/console pteroca:dev:upgrade-theme my-theme --no-backup

What the Command Does

1. Creates backup - Automatically backs up theme to themes/{theme-name}.backup.{timestamp}/

2. Restructures directories - Creates panel/, landing/, and email/ folders

3. Migrates templates - Moves existing templates to panel/ context

4. Copies landing templates - Adds landing page templates from default theme

5. Updates template.json - Adds contexts field with appropriate values

6. Preserves customizations - Keeps all custom templates and assets intact

Migration Process

Before (v0.6.2 and earlier):

themes/my-theme/
├── template.json
├── bundles/
├── components/
└── email/

After (v0.6.3+):

themes/my-theme/
├── template.json (updated with contexts field)
├── panel/
│   ├── bundles/
│   └── components/
├── landing/
│   └── (landing page templates)
└── email/

Backup and Rollback

Automatic backup:

• Creates timestamped backup: themes/{theme-name}.backup.{timestamp}/

• Complete copy of theme before any changes

• Allows easy rollback if needed

To rollback:

# Remove upgraded theme
rm -rf themes/my-theme

# Restore backup
mv themes/my-theme.backup.20260203-143022 themes/my-theme

# Clear cache
php bin/console cache:clear

Always Backup in Production

Unless you're using Git or another version control system, always allow the automatic backup. The --no-backup flag is intended for development environments with VCS.

---

Related Development Guides

• Theme Development - Complete theme development guide

• Plugin Development - Create custom plugins

• Translation System - Multi-language support

Additional Developer Commands

Symfony Debug Commands

# List all routes
php bin/console debug:router

# List all services
php bin/console debug:container

# List all events
php bin/console debug:event-dispatcher

# List all translations
php bin/console debug:translation

Cache Commands

# Clear cache
php bin/console cache:clear

# Warm up cache
php bin/console cache:warmup

Database Commands

# Run migrations
php bin/console doctrine:migrations:migrate

# Check mapping
php bin/console doctrine:schema:validate

Best Practices

1. Always test in development - Use APP_ENV=dev for better error messages

2. Version control - Track theme and translation changes in git

3. Backup before changes - Always backup before making significant changes

4. Follow conventions - Use established naming conventions for themes and translations

5. Document customizations - Add comments explaining theme modifications

Related Guides

• CLI Commands Overview - Command reference home

• Theme Development - Create themes

• Plugin Development - Create plugins