Download the PHP package julienlinard/php-carousel without Composer

PHP Carousel

🇬🇧 Read in English

💝 Support the project

If this bundle is useful to you, consider becoming a sponsor to support the development and maintenance of this open source project.

A modern and performant carousel library for PHP with beautiful designs. Pure CSS/JS native implementation with zero external dependencies.

🚀 Installation

Requirements: PHP 8.2 or higher

Optional Dependencies

The core library has zero external dependencies. However, if you want to use Twig or Blade integrations, you need to install the corresponding packages:

For Twig integration:

For Blade integration (Laravel):

Note: These dependencies are optional. The core carousel functionality works without them. They are only needed if you use the Twig or Blade extensions.

⚡ Quick Start

Simple Image Carousel

Card Carousel

Testimonial Carousel

🎨 Visual Demos

See the carousels in action! Each type is fully customizable and responsive with smooth animations.

Image Carousel

Perfect for hero banners and image galleries with smooth slide transitions.

Card Carousel

Ideal for product listings, blog posts, or feature showcases. Displays multiple items per slide.

Testimonial Carousel

Beautiful fade transitions for customer reviews and testimonials.

Gallery Carousel

Advanced gallery with thumbnail navigation for easy browsing.

📋 Features

• ✅ Zero Dependencies - Pure CSS/JS native implementation
• ✅ Multiple Types - Image, Card, Testimonial, Gallery, Infinite carousels
• ✅ Static Factory Methods - infiniteCarousel(), heroBanner(), productShowcase(), testimonialSlider()
• ✅ Twig & Blade Integration - Ready-to-use extensions for popular templating engines
• ✅ Fully Responsive - Mobile, tablet, and desktop optimized
• ✅ Touch Swipe - Native touch gestures support
• ✅ Keyboard Navigation - Accessible keyboard controls
• ✅ Autoplay - Configurable autoplay with pause on hover
• ✅ Smooth Animations - CSS transitions and transforms
• ✅ Lazy Loading - Built-in image lazy loading with Intersection Observer
• ✅ Customizable - Extensive configuration options
• ✅ WCAG 2.1 AA Compliant - Full accessibility support (ARIA, screen readers, prefers-reduced-motion)
• ✅ Security - XSS prevention, URL validation, input sanitization
• ✅ Performance - Modular renderer architecture, optimized JavaScript, CSS/JS minification, virtualization for large carousels
• ✅ Themes - Dark/Light mode support with automatic system preference detection
• ✅ Virtualization - Automatic performance optimization for carousels with 50+ items
• ✅ Server-Side Rendering (SSR) - Static HTML generation for SEO and CDN caching
• ✅ Built-in Analytics - Automatic tracking of impressions, clicks, and interactions with detailed reports
• ✅ A/B Testing Built-in - Integrated variant testing with cookie, hash, or random selection
• ✅ Error Handling - Image error placeholders, loading indicators

📖 Documentation

Core Documentation

• API Reference - Complete API documentation
• Best Practices - Production-ready guidelines
• Migration Guide - Migrate from Swiper.js
• Troubleshooting - Common issues and solutions

Advanced Topics

• Security policy and best practices - Reporting vulnerabilities, secure usage
• Accessibility Guide - WCAG 2.1 AAA compliance
• Performance Guide - Optimization techniques
• Cache and HTTP headers - Cache-Control, ETag (app responsibility)
• E2E Testing - End-to-end testing guide

Integration Guides

• CMS Integration - WordPress, PrestaShop, Drupal
• Twig Integration - Twig templating engine
• Blade Integration - Laravel Blade templating
• React Integration - React.js integration
• Vue Integration - Vue.js integration

Examples & Tutorials

• CodePen Examples - Interactive examples
• Video Tutorials - Tutorial scripts
• Usage Examples - Code examples

Carousel Types

Image Carousel

Perfect for image galleries and hero banners.

Card Carousel

Ideal for product listings, blog posts, or feature cards.

Testimonial Carousel

Perfect for customer reviews and testimonials.

Gallery Carousel

Advanced gallery with thumbnails navigation.

Configuration Options

Advanced Usage

Custom Items

Separate HTML, CSS, and JS

Dark/Light Theme Support

Virtualization for Large Carousels

Custom Transitions and Animations

Export/Import Configuration

Server-Side Rendering (SSR)

SSR Benefits:

• ✅ Perfect SEO (content in HTML)
• ✅ Fast initial load (no JavaScript required)
• ✅ CDN cacheable
• ✅ Progressive enhancement (add JS when needed)

Built-in Analytics

A/B Testing Built-in

Multiple Carousels on Same Page

🎨 Styling

The carousel uses pure CSS with no external dependencies. All styles are scoped to the carousel container to avoid conflicts.

Custom Styling

You can override styles using CSS:

📚 API Reference

Carousel Class

Static Factory Methods

• Carousel::image(string $id, array $images, array $options = []): self - Image carousel
• Carousel::card(string $id, array $cards, array $options = []): self - Card carousel
• Carousel::testimonial(string $id, array $testimonials, array $options = []): self - Testimonial carousel
• Carousel::gallery(string $id, array $images, array $options = []): self - Gallery carousel
• Carousel::infiniteCarousel(string $id, array $images, array $options = []): self - Infinite scrolling carousel
• Carousel::heroBanner(string $id, array $banners, array $options = []): self - Hero banner carousel
• Carousel::productShowcase(string $id, array $products, array $options = []): self - Product showcase carousel
• Carousel::testimonialSlider(string $id, array $testimonials, array $options = []): self - Testimonial slider

Instance Methods

• addItem(CarouselItem|array $item): self - Add a single item
• addItems(array $items): self - Add multiple items
• setOptions(array $options): self - Set carousel options
• getOption(string $key, mixed $default = null): mixed - Get an option value
• render(): string - Render complete carousel (HTML + CSS + JS)
• renderHtml(): string - Render only HTML
• renderCss(): string - Render only CSS
• renderJs(): string - Render only JavaScript
• renderStatic(): string - Render static HTML with CSS (SSR, no JS)
• hydrate(string $staticHtml): string - Add JavaScript to static HTML
• getId(): string - Get carousel ID
• getType(): string - Get carousel type
• getItems(): array - Get all items
• getOptions(): array - Get all options
• exportConfig(): array - Export configuration to array
• fromConfig(array $config): self - Create carousel from configuration (static)

CarouselItem Class

Constructor

Static Methods

• CarouselItem::fromArray(array $data): self - Create from array

Instance Methods

• toArray(): array - Convert to array

💡 Examples

Example 1: Product Carousel

Example 2: Hero Banner Carousel

Example 3: Customer Testimonials

🔌 Integrations

Twig Integration

See INTEGRATION_TWIG.md for complete documentation.

Blade Integration (Laravel)

See INTEGRATION_BLADE.md for complete documentation.

🧪 Tests

Test Coverage:

• ✅ 60 tests, 200 assertions
• ✅ Security tests (XSS prevention, URL validation, input sanitization)
• ✅ Accessibility tests (ARIA attributes, screen readers, prefers-reduced-motion)
• ✅ Integration tests (Twig, Blade)
• ✅ Functional tests (all carousel types and methods)

📚 Additional Documentation

• API Reference - Complete API documentation
• Twig Integration - Twig extension guide
• Blade Integration - Laravel Blade guide
• Usage Examples - More examples

📝 License

MIT License - See the LICENSE file for more details.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or a pull request.

📧 Support

For any questions or issues, please open an issue on GitHub.

💝 Support the project

If this bundle is useful to you, consider becoming a sponsor to support the development and maintenance of this open source project.

Developed with ❤️ by Julien Linard