A server for debugging more than just Laravel applications.

Just a month ago, I came across a curious app Ray from spatie— an application with a minimalist interface for displaying debug information (values of variables, errors, logs, etc.) during application development.

Ray app

The Ray app isn’t bound to specific framework, programming language or environment. In the PHP world the application works with spatie/ray package. There are also packages and libraries in other languages that work with the Ray app.

I wanted to see how it works from the inside, and I liked the idea so much that I developed a working analogue, which has almost all the functionality of the original, as well as additional features. I named it the Ray server.

The Ray server is a free alternative for those who want to run a server without GUI, cannot afford the paid version or just like open source.

As I said, the Ray app isn’t bound to a specific framework and programming language and is a multipurpose tool. However I wanted to make it a little different, similar to MailHog. If someone doesn’t know about MailHog — it is an SMTP-server for receiving test emails during development, which can be run in seconds via Docker and doesn’t require additional settings from the project’s side. I wanted the RayServer to have the same ability — run via Docker and easily be able to become a part of any project, even if there is an OS without GUI.

The Ray app receives events and logs from various sources, and then displays them in a nice looking way, providing detailed information for each type of event.

  1. When the Ray app starts, it launches a web server on port 23517.
  2. package sends requests via HTTP to the Ray app and events display in the application window.

It looked understandable, and I thought: “Why not try to develop something similar, only in the form of a web server?” I also wanted to use a simple stack of technologies, just Laravel and Docker.

  • display variables, logs and errors — this is one of the main features;
  • be free for everyone (Open Source project);
  • be extendable by contributors;
  • ease of use during development;
  • independence from the programming language and framework.

I managed to complete all the tasks that I set at the beginning of my journey into the magical world of debugging. I developed an open source application — the RayServer, which displays events in a beautiful, readable way and solves the main problem of application debugging. At the same time the server is as simple as possible, and everyone can contribute to it.

Some of the RayServer features

The RayServer API is compatible with Sentry, making it a lightweight alternative for local development.

The RayServer is compatible with monolog/monolog composer package, and can display logs from it.

The RayServer also is an email testing tool that makes it super easy to install and configure a local email server. The RayServer sets up a fake SMTP server and you can configure your preferred web applications to use RayServer’s SMTP server to send and receive emails. For instance, you can configure a local WordPress site to use RayServer for email deliveries.

The RayServer has a lightweight and nice UI that allows you to view events, filtering them by label, type and color.

The RayServer is fully compatible with all features of the spatie/ray and spatie/laravel-ray packages.

UI has a responsive design and a mobile device can be used as an additional screen for viewing event history.

The RayServer is written on Laravel + Octane HTTP/Websocket and is open source under the MIT license. Anyone can contribute to it.

Code examples can be found here.

Installing and running the RayServer

The easiest way to run the RayServer is a Docker container. After running the docker container, the server is ready to receive events, and doesn’t require any additional configuration.

// Latest version
docker run --pull always -p 23517:8000 -p 1025:1025 butschster/debugger:latest
// Specific version
docker run -p 23517:8000 -p 1025:1025 butschster/debugger:v1.15.2

A dashboard is available at http://127.0.0.1:23517

By default, the RayServer uses sqlite database for storing events. Furthermore, you can use an external database:

// docker-compose.yml
version: "2"
services:
php:
image: butschster/debugger:latest
environment:
DB_CONNECTION: pgsql
DB_HOST: db
DB_DATABASE: homestead
DB_USERNAME: homestead
DB_PASSWORD: secret
ports:
- 23517:8000
- 1025:1025
depends_on:
- db
db:
image: postgres
environment:
POSTGRES_USER: homestead
POSTGRES_DB: homestead
POSTGRES_PASSWORD: secret

It uses port 23517 by default and there is no need for additional configuration.

// For Laravel
RAY_HOST=127.0.0.1
RAY_PORT=23517

The RayServer is compatible with https://sentry.io/, so you can specify DSN in your application:

// Laravel
SENTRY_LARAVEL_DSN=http://sentry@127.0.0.1:23517/1

There is a \Monolog\Handler\SlackWebhookHandler handler that allows you to specify an url for sending data.

// Laravel
LOG_CHANNEL=slack
LOG_SLACK_WEBHOOK_URL=http://127.0.0.1:23517/slack

The RayServer runs an SMTP server and can be used as an email testing tool.

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
  • Install php extension — swoole
  • Clone the project code to the directory.
  • Run the composer install command.
  • Start the server.
php artisan server:start --host=127.0.0.1 --port=23517
php artisan smtp:start --host=127.0.0.1 --port=1025

Enjoy!

I hope you will love my humble but beloved RayServer. All information about it can be found at the links below:

Full Stack PHP Developer