PHP-GLFW

Website • Getting Started • User Guide • API Docs

A fully-featured OpenGL and GLFW extension for PHP. Batteries included 🔋!

PHP-GLFW allows you to create 2D and 3D real-time applications in PHP. Bringing a whole different set of tools into the PHP world to develop graphical applications like games, scientific simulations, user interfaces and co.

• What is this extension? Features 🚀
  • OpenGL
  • GLFW
  • PHPGL - Math
  • PHPGL - Buffers
  • PHPGL - Textures
  • How are the bindings achieved?
• Documentation 📚
  • Examples
• Installation
  • MacOS
  • Linux
  • Stubs (IDE Support)
• Things to know when you start 💡
• Credits
• License

What is this extension? Features 🚀

PHP-GLFW aims to be one extension containing all basics you need to start building graphical applications in PHP. That means that PHP-GLFW does NOT just provide GLFW library bindings. Instead, it also includes OpenGL bindings and a bunch of classes and helpers pretty much required for building these types of applications.

OpenGL

• Full native support of OpenGL (4.1+ core), GPU accelerated rendering in PHP.
• Targeting OpenGL 4.1, but it can also be built for newer versions.
• Support for OpenGL extensions (limited).
• Mostly mirroring the C API, adjustments were made where required or otherwise nonsensical.
• We currently support about ~90% of the full standard, check GLSUPPORT.md

GLFW

This extension comes obviously with bindings for the amazing GLFW library. GLFW comes with great features, to name a few:

• Multiplatform Window creation and handling. (MacOS / Window / Linux)
• Support for multiple windows and monitors.
• Real-time user input handling.
  • Keyboard and Mouse event handling.
  • Joystick input support.

PHPGL - Math

PHPGL is what I call the extras in this extension, aka classes and helpers additionally provided that are pretty much a requirement for these kinds of applications. PHP-GLFW comes with a mathematics library written in C, covering the most common operations required for graphical applications.

• Supported structs: Vec2, Vec3, Vec4, Mat4 and Quat.
• Includes most common matrix operations for the use case like: lookAt, perspective, inverse, rotate etc..

Having this integrated into the extension comes with a bunch of advantages:

• It's fast.
• low memory footprint.
• The math structures have overloaded operators, so you can write things like:

  $v3 = Vec2(15, -5) + Vec2(42, 7); // returns Vec2(54, 2)

• Some OpenGL functions can directly accept the math structs as arguments.

PHPGL - Buffers

This extension also contains a collection of buffer objects that internally hold data in native types.

• Can handle large arrays of data.
• Low memory footprint and very fast.
• Data is stored internally to be directly uploadable to the GPU.

PHPGL - Textures

PHP-GLFW supports the loading of images/textures into buffers without requiring an additional extension:

• can load common image formats as jpg, png, tga, bmp, gif. (gd or Imagick is not required)
• can write images/textures back to disk.
• writes data into a BufferInterface object giving full access to the bitmap from userland.

How are the bindings achieved?

Instead of porting function by function manually, PHP-GLFW parses the OpenGL specs to generate most of this C extension. Adjustments are made manually where necessary.

Documentation 📚

1. Full Documentation
2. Getting Started Guide
3. User Guide
4. API Docs

Examples

If you want to check out the code straight away, check out the examples directory.

Installation

Please see the complete detailed installation guide here: Installation

MacOS

Installer

There is a simple installer script you can use to install php-gflw:

php -r "copy('https://raw.githubusercontent.com/mario-deluna/php-glfw/master/install/macos-installer.php', 'phpglfw-installer.php');" && php phpglfw-installer.php

Thats it, if you see the text "Installation finished!" you should be ready to go!

Manual installation

If you prefer a manual approach, ensure you have installed the php-dev, git and cmake packages. They are required!

git clone https://github.com/mario-deluna/php-glfw
cd php-glfw
sudo phpize && ./configure --enable-glfw
sudo make install

make sure to add glfw.so in the php.ini file:

extension="glfw.so"

Linux

cmake is required for the installation. You can skip the first step if it's already installed. Also, make sure that you install the php-dev package for example, php8.1-dev.

sudo apt install -y cmake git 
git clone https://github.com/mario-deluna/php-glfw
cd php-glfw
sudo phpize && ./configure --enable-glfw
sudo make install

make sure to add glfw.so in the php.ini file:

extension="glfw.so"

Stubs (IDE Support)

As this is a PHP extension, your editor / IDE does not support auto-completion and doc lookups without some help. We created a composer package you can include as a dev dependency to have full support:

composer require --dev phpgl/ide-stubs

Things to know when you start 💡

PHP-GLFW tries to keep the core OpenGL / GLFW API as close to the original as possible and only modifies the API when necessary. This results in some functions being quite wired from a PHP point of view. Naming scheme:

prefix	module	desc
gl	OpenGL	Core OpenGL functions. Examples: glClearColor, glEnable, glActiveTexture etc.
glfw	GLFW	GLFW library functions, everything to interact with the OS window, input. Examples: glfwCreateWindow, glfwGetCursorPos, glfwSwapBuffers
GL\	PHP-GLFW	Classes and functions in this namespace are custom to the extension and are not default to OpenGL. Examples: GL\Buffer\FloatBuffer, GL\Math\Vec3 etc..

Credits

• Mario Döring
• All Contributors

License

Please see License File for more information.