concept-labs/singularity

(C)oncept-Labs Singularity. Dependency Injection pack

1.3.3 2025-10-25 11:05 UTC

Requires

• php: >=8.2
• concept-labs/composer: ^1
• concept-labs/config: ^2
• concept-labs/simple-cache: ^1
• psr/container: ^2

Requires (Dev)

• pestphp/pest: ^2.0

MIT

• Viktor Halytskyi

• dependency injection
• container
• php
• di
• PSR-11
• singularity

README

Comprehensive documentation for the Singularity Dependency Injection Container.

Requirements

• PHP Version: >= 8.2
• PSR-11: Container Interface ^2.0
• Dependencies:
  • psr/container ^2
  • concept-labs/config ^2
  • concept-labs/simple-cache ^1
  • concept-labs/composer ^1

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Concept-Labs

Table of Contents

Getting Started

1. Overview - Introduction to Singularity DI

   • What is Singularity DI?
   • Key features
   • Core components
   • How it works
   • Use cases

2. Getting Started - Quick start guide

   • Installation
   • Basic setup
   • Complete examples
   • Common patterns
   • Debugging tips

Core Concepts

1. Configuration - Configuration reference

   • Configuration structure
   • Package-level configuration (recommended)
   • Namespace configuration
   • Global preferences
   • Plugin configuration
   • Advanced configuration techniques (@include, @import, ${VAR})
   • Environment-specific config
   • Best practices

2. Context Builder - Dependency resolution

   • How it works
   • Configuration hierarchy
   • ProtoContext structure
   • Dependency resolution
   • Argument resolution
   • Performance optimization

3. Lifecycle Management - Service lifecycle

   • Lifecycle patterns (Transient, Shared, Weak, Prototype)
   • Service registry
   • Memory management
   • Lifecycle events
   • Best practices

Advanced Features

1. Plugin System - Plugin development

   • Plugin interface
   • Creating custom plugins
   • Registering plugins
   • Built-in plugins
   • Advanced patterns
   • Best practices

2. Factories - Factory pattern

   • Factory interface
   • Creating factories
   • Factory patterns (Abstract, Builder, Multiton, Lazy)
   • ServiceFactory
   • Testing factories

3. Contracts - Built-in interfaces

   • Initialization contracts (Injectable, AutoConfigure)
   • Lifecycle contracts (Shared, Weak, Prototype)
   • Factory contracts (LazyGhost)
   • Combining contracts
   • Creating custom contracts

4. Advanced Usage - Complex scenarios

   • Multi-tenant applications
   • Middleware pattern
   • Decorator pattern
   • Event-driven architecture
   • Aspect-oriented programming
   • Dynamic service registration
   • Circular dependency resolution
   • Performance optimization
   • Testing patterns

Reference

1. API Reference - Complete API documentation
   • Core classes
   • Plugin system
   • Factory system
   • Contracts
   • Exceptions
   • Configuration structure
   • Built-in plugins

Quick Links

Common Tasks

• Install and Setup: Getting Started → Installation
• Configure Services: Configuration → Package Configuration
• Advanced Config Techniques: Configuration → Advanced Configuration Techniques
• Create a Plugin: Plugins → Creating Custom Plugins
• Use Factories: Factories → Creating a Factory
• Manage Lifecycle: Lifecycle → Lifecycle Patterns
• Advanced Patterns: Advanced Usage

By Use Case

• Multi-Tenant Apps: Advanced Usage → Multi-Tenant Applications
• Testing: Advanced Usage → Testing Patterns
• Performance: Advanced Usage → Performance Optimization
• AOP: Advanced Usage → Aspect-Oriented Programming

By Feature

• Autowiring: Getting Started → Working Without Configuration
• Lazy Loading: Contracts → LazyGhostInterface
• Singleton Pattern: Contracts → SharedInterface
• Prototype Pattern: Contracts → PrototypeInterface
• Method Injection: Contracts → InjectableInterface

Documentation Structure

Each documentation file follows a consistent structure:

1. Overview - Introduction to the topic
2. Core Concepts - Fundamental knowledge
3. Examples - Practical code examples
4. Advanced Topics - Complex scenarios
5. Best Practices - Recommended patterns
6. Next Steps - Links to related topics

Code Examples

All code examples in this documentation are:

• Complete - Can be copied and run
• Tested - Based on actual working code
• Commented - Include explanatory comments
• Progressive - Start simple, build complexity

Conventions

Code Blocks

// PHP code examples
$container = new Singularity($config);

// JSON configuration examples
{
  "singularity": {
    "preference": {}
  }
}

Symbols

• ✅ Good practice - Recommended approach
• ❌ Anti-pattern - Avoid this
• ⚠️ Warning - Use with caution
• 💡 Tip - Helpful information

Contributing

Found an error or want to improve the documentation?

1. Make your changes
2. Submit a pull request
3. Include clear description of changes

License

This documentation is part of the Singularity DI project and is covered by the same license.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Source Code: GitHub Repository

Start Learning: Begin with the Overview or jump to Getting Started for a hands-on introduction.