{"id":34639847,"url":"https://github.com/projectsaturnstudios/phpdafruit_ssd1306-php","last_synced_at":"2026-01-20T16:36:28.110Z","repository":{"id":313995316,"uuid":"1053735777","full_name":"projectsaturnstudios/phpdafruit_ssd1306-php","owner":"projectsaturnstudios","description":"Intermediate package for interfacing with Phdafruit_SSD1306 extension made by ProjectSaturnStudios","archived":false,"fork":false,"pushed_at":"2025-10-23T07:15:00.000Z","size":125,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-18T13:14:07.709Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/projectsaturnstudios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T21:21:53.000Z","updated_at":"2025-10-23T07:14:13.000Z","dependencies_parsed_at":"2025-10-23T09:14:19.308Z","dependency_job_id":"0b054e9d-eddb-4090-9a0a-7581518bdb0d","html_url":"https://github.com/projectsaturnstudios/phpdafruit_ssd1306-php","commit_stats":null,"previous_names":["projectsaturnstudios/ssd1306","projectsaturnstudios/ssd1306-php","projectsaturnstudios/phpdafruit_ssd1306-php"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/projectsaturnstudios/phpdafruit_ssd1306-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fphpdafruit_ssd1306-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fphpdafruit_ssd1306-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fphpdafruit_ssd1306-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fphpdafruit_ssd1306-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projectsaturnstudios","download_url":"https://codeload.github.com/projectsaturnstudios/phpdafruit_ssd1306-php/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fphpdafruit_ssd1306-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28005414,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T17:15:39.770Z","updated_at":"2025-12-24T17:15:40.852Z","avatar_url":"https://github.com/projectsaturnstudios.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SSD1306 PHP Package\n\nA comprehensive, production-ready PHP library for controlling SSD1306 OLED displays via I2C. Built on top of the `php-ssd1306-i2c` extension with high-level services, animations, state machines, and UI components.\n\n## Features\n\n🎨 **Rich Feature Set:**\n- **Builder Pattern**: Fluent display configuration with presets\n- **Text Rendering**: Advanced text rendering with effects (scroll, typewriter, marquee, fade)\n- **Shape Rendering**: Progress bars, gauges, rounded boxes, icons\n- **Animation Engine**: Frame-based animations with timing control\n- **State Machine**: Manage display states with smooth transitions\n- **UI Components**: Menus, notifications, dashboards, widgets\n- **Math Utilities**: 2D vectors, matrices, curves, and easing functions\n- **Traits \u0026 Interfaces**: Composable functionality with `HasAnimations`, `HasEffects`, `Renderable`\n\n🧪 **Production Ready:**\n- 450+ comprehensive Pest tests\n- All tests run on actual hardware\n- Zero segfaults with proper resource management\n- Full PSR-4 autoloading\n\n## Requirements\n\n- PHP 8.1+\n- `php-ssd1306-i2c` extension installed\n- `php-adafruit-gfx` extension installed\n- I2C device access (e.g., `/dev/i2c-7`)\n\n## Installation\n\n```bash\ncomposer require phpdafruit/ssd1306-php\n```\n\n## Quick Start\n\n```php\n\u003c?php\n\nuse PhpdaFruit\\SSD1306\\Builder\\DisplayFactory;\nuse PhpdaFruit\\SSD1306\\Services\\TextRenderer;\nuse PhpdaFruit\\SSD1306\\Effects\\TypewriterText;\n\n// Create display using factory\n$display = DisplayFactory::standard('/dev/i2c-7');\n\n// Render text with typewriter effect\n$textRenderer = new TextRenderer($display);\n$effect = new TypewriterText();\n\nfor ($i = 0; $i \u003c 10; $i++) {\n    $display-\u003eclearDisplay();\n    $effect-\u003erender($display, 'Hello World!', 10, 12, $i / 10);\n    $display-\u003edisplay();\n    usleep(100000);\n}\n```\n\n## Core Components\n\n### 1. Display Builder\n\nCreate and configure displays with a fluent API:\n\n```php\nuse PhpdaFruit\\SSD1306\\Builder\\DisplayBuilder;\nuse PhpdaFruit\\SSD1306\\Builder\\DisplayFactory;\n\n// Manual configuration\n$display = (new DisplayBuilder())\n    -\u003ewithDisplay(128, 32, '/dev/i2c-7')\n    -\u003ewithBrightness(200)\n    -\u003ewithRotation(0)\n    -\u003ebuild();\n\n// Or use presets\n$display = DisplayFactory::standard('/dev/i2c-7');\n$display = DisplayFactory::highContrast('/dev/i2c-7');\n$display = DisplayFactory::dimmed('/dev/i2c-7');\n```\n\n### 2. Text Rendering \u0026 Effects\n\nRender text with various effects:\n\n```php\nuse PhpdaFruit\\SSD1306\\Services\\TextRenderer;\nuse PhpdaFruit\\SSD1306\\Effects\\{ScrollingText, TypewriterText, MarqueeText, FadeText};\n\n$renderer = new TextRenderer($display);\n\n// Scrolling text\n$scroll = new ScrollingText('horizontal', 2);\n$scroll-\u003erender($display, 'Scrolling...', 0, 10, 0.5);\n\n// Typewriter effect\n$typewriter = new TypewriterText();\n$typewriter-\u003erender($display, 'Typing...', 10, 10, 0.75);\n\n// Positioned text\n$renderer-\u003eleftAlign('Left', 0, 0);\n$renderer-\u003ecenterAlign('Center', 16);\n$renderer-\u003erightAlign('Right', 24);\n```\n\n### 3. Shape Rendering\n\nDraw progress bars, gauges, and more:\n\n```php\nuse PhpdaFruit\\SSD1306\\Services\\ShapeRenderer;\nuse PhpdaFruit\\SSD1306\\Shapes\\{ProgressBar, Gauge, RoundedBox, Icon};\n\n$shapeRenderer = new ShapeRenderer($display);\n\n// Progress bar\n$progressBar = new ProgressBar(10, 10, 100, 8);\n$progressBar-\u003esetValue(75);\n$shapeRenderer-\u003erenderProgressBar($progressBar);\n\n// Gauge\n$gauge = new Gauge(64, 16, 15);\n$gauge-\u003esetValue(65)-\u003esetRange(0, 100);\n$shapeRenderer-\u003erenderGauge($gauge);\n\n// Rounded box\n$box = new RoundedBox(5, 5, 118, 22, 3);\n$shapeRenderer-\u003erenderRoundedBox($box);\n\n// Icons\nIcon::initializeBuiltIns();\n$icon = Icon::get('wifi');\n$shapeRenderer-\u003erenderIcon($icon, 50, 12);\n```\n\n### 4. Animation Engine\n\nCreate smooth frame-based animations:\n\n```php\nuse PhpdaFruit\\SSD1306\\Services\\AnimationEngine;\n\n$animation = new AnimationEngine($display);\n\n// Add frames\nfor ($x = 0; $x \u003c 100; $x += 10) {\n    $animation-\u003eaddFrame(function($disp, $progress) use ($x) {\n        $disp-\u003efillCircle($x, 16, 5, 1);\n    }, 100); // 100ms per frame\n}\n\n// Control playback\n$animation-\u003eloop(true);\n$animation-\u003eplay();\n```\n\n### 5. State Machine\n\nManage display states with transitions:\n\n```php\nuse PhpdaFruit\\SSD1306\\StateMachine\\{StateMachine, Transition};\nuse PhpdaFruit\\SSD1306\\StateMachine\\States\\{IdleState, AlertState, DashboardState};\n\n$stateMachine = new StateMachine($display);\n\n// Register states\n$stateMachine-\u003eaddState('idle', new IdleState($display));\n$stateMachine-\u003eaddState('alert', new AlertState($display, 'Warning!'));\n$stateMachine-\u003eaddState('dashboard', new DashboardState($display));\n\n// Set initial state\n$stateMachine-\u003esetInitialState('idle');\n\n// Transition with fade effect\n$transition = new Transition(0.5, Curve::easeInOut(...), 'fade');\n$stateMachine-\u003etransition('alert', $transition);\n\n// Update and render\n$stateMachine-\u003eupdate(0.016); // Delta time\n$stateMachine-\u003erender();\n```\n\n### 6. UI Components\n\nBuild interactive interfaces:\n\n```php\nuse PhpdaFruit\\SSD1306\\UI\\{Menu, Notification, Dashboard};\nuse PhpdaFruit\\SSD1306\\UI\\Widgets\\{TextWidget, ProgressWidget, IconWidget, GraphWidget};\n\n// Menu\n$menu = new Menu($display);\n$menu-\u003eaddItem('Settings', fn() =\u003e loadSettings())\n     -\u003eaddItem('Display', fn() =\u003e displayMenu())\n     -\u003eaddItem('About', fn() =\u003e showAbout());\n     \n$menu-\u003eselectNext();\n$menu-\u003erender();\n\n// Notification\n$notification = Notification::info($display, 'System Ready', 3.0);\n$notification-\u003eshow();\n\n// Dashboard with widgets\n$dashboard = new Dashboard($display, 2, 2);\n\n$cpu = new ProgressWidget($display);\n$cpu-\u003esetLabel('CPU')-\u003esetValue(65);\n\n$mem = new ProgressWidget($display);\n$mem-\u003esetLabel('MEM')-\u003esetValue(78);\n\n$dashboard-\u003eaddWidget($cpu, 0, 0)\n          -\u003eaddWidget($mem, 0, 1);\n          \n$dashboard-\u003erender();\n```\n\n### 7. Math Utilities\n\nVector and matrix operations:\n\n```php\nuse PhpdaFruit\\SSD1306\\Math\\{Vector2D, Matrix2D, Curve};\n\n// Vector operations\n$v1 = new Vector2D(10, 20);\n$v2 = new Vector2D(5, 10);\n$sum = $v1-\u003eadd($v2);\n$magnitude = $v1-\u003emagnitude();\n\n// Matrix transformations\n$matrix = Matrix2D::rotation(M_PI / 4);\n$transformed = $matrix-\u003etransform($v1);\n\n// Easing functions\n$eased = Curve::easeInOut(0.5);\n$bezier = Curve::cubicBezier($p0, $p1, $p2, $p3, 0.5);\n```\n\n### 8. Traits \u0026 Interfaces\n\nAdd composable functionality:\n\n```php\nuse PhpdaFruit\\SSD1306\\Concerns\\{HasAnimations, HasEffects, Renderable};\n\nclass MyWidget implements Renderable {\n    use HasAnimations;\n    use HasEffects;\n    \n    public function render(): void {\n        // Render logic\n    }\n    \n    // Interface requirements\n    public function getBounds(): array { /* ... */ }\n    public function setVisible(bool $visible): self { /* ... */ }\n    public function isVisible(): bool { /* ... */ }\n}\n\n// Use the widget\n$widget = new MyWidget($display);\n$widget-\u003eanimate(fn($d, $p) =\u003e /* frame render */, 500, true);\n$widget-\u003ewithEffect(new ScrollingText());\n```\n\n## Architecture\n\n```\nsrc/\n├── SSD1306Display.php           # Core display wrapper\n├── Builder/                      # Display creation\n│   ├── DisplayBuilder.php\n│   └── DisplayFactory.php\n├── Services/                     # High-level services\n│   ├── TextRenderer.php\n│   ├── ShapeRenderer.php\n│   └── AnimationEngine.php\n├── Math/                         # Mathematical utilities\n│   ├── Vector2D.php\n│   ├── Matrix2D.php\n│   └── Curve.php\n├── StateMachine/                 # State management\n│   ├── DisplayState.php\n│   ├── StateMachine.php\n│   ├── Transition.php\n│   └── States/\n├── Effects/                      # Text effects\n│   ├── TextEffect.php\n│   ├── ScrollingText.php\n│   ├── TypewriterText.php\n│   ├── MarqueeText.php\n│   └── FadeText.php\n├── Shapes/                       # Shape objects\n│   ├── ProgressBar.php\n│   ├── Gauge.php\n│   ├── RoundedBox.php\n│   └── Icon.php\n├── UI/                          # UI components\n│   ├── Menu.php\n│   ├── Notification.php\n│   ├── Dashboard.php\n│   ├── Widget.php\n│   └── Widgets/\n└── Concerns/                    # Traits \u0026 Interfaces\n    ├── HasAnimations.php\n    ├── HasEffects.php\n    └── Renderable.php\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\n# All tests\n./vendor/bin/pest\n\n# Specific test suites\n./vendor/bin/pest tests/Unit/\n./vendor/bin/pest tests/Feature/\n\n# With coverage\n./vendor/bin/pest --coverage\n```\n\n## Examples\n\nSee [EXAMPLES.md](EXAMPLES.md) for complete usage scenarios including:\n- System monitor dashboard\n- Interactive menu system\n- Animated splash screen\n- Notification system\n- State machine workflows\n\n## Best Practices\n\n### Resource Management\n\nAlways use a single `SSD1306Display` instance and pass it to services:\n\n```php\n// ✅ Good - Single instance\n$display = DisplayFactory::standard('/dev/i2c-7');\n$textRenderer = new TextRenderer($display);\n$shapeRenderer = new ShapeRenderer($display);\n\n// ❌ Bad - Multiple instances can cause segfaults\n$display1 = new SSD1306Display(128, 32, '/dev/i2c-7');\n$display2 = new SSD1306Display(128, 32, '/dev/i2c-7'); // Don't do this!\n```\n\n### Display Lifecycle\n\nAlways clear before rendering and display after drawing:\n\n```php\n$display-\u003eclearDisplay();\n// ... draw operations ...\n$display-\u003edisplay();\n```\n\n### Animation Timing\n\nUse consistent delta time for smooth animations:\n\n```php\n$lastTime = microtime(true);\nwhile (true) {\n    $currentTime = microtime(true);\n    $deltaTime = $currentTime - $lastTime;\n    $lastTime = $currentTime;\n    \n    $stateMachine-\u003eupdate($deltaTime);\n    $stateMachine-\u003erender();\n}\n```\n\n## License\n\nMIT License - See LICENSE file for details\n\n## Credits\n\nBuilt by Angel Gonzalez (@projectsaturnstudios)\nBased on `php-ssd1306-i2c` and `php-adafruit-gfx` extensions\n\n## Contributing\n\nContributions welcome! Please ensure:\n- All tests pass on actual hardware\n- New features include comprehensive Pest tests\n- Code follows PSR-12 standards\n- Documentation is updated\n\n## Support\n\nFor issues, questions, or contributions, please visit the GitHub repository.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectsaturnstudios%2Fphpdafruit_ssd1306-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojectsaturnstudios%2Fphpdafruit_ssd1306-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectsaturnstudios%2Fphpdafruit_ssd1306-php/lists"}