IxDF Developer Docs

Appearance

Buggregator ​

For local env, we have buggregator service in the docker-compose.yml file. You can use Buggregator for few purposes. Buggregator UI is available at http://localhost:8100 (configurable by the DOCKER_FORWARD_BUGGREGATOR_PORT env var).

What is Buggregator under the hood?

Technically, Buggregator is a container with few services that works on different protocols:

  • 8000: a website runs on RoadRunner that has few API endpoints for different services. Listen to WebSocket connections from other services.
  • 1025: standard SMTP server that catches all emails sent from your application.
  • 9912: Symfony Var-Dumper server. Receives data sent by dump() function and redirects it to 8100 API endpoint to display on web UI
  • 9913: Logs client. Received data sent by Laravel logger and redirects it to 8000 API endpoint to display on web UI

1. VarDump server ​

Default behavior of the dump() function is to output data to the response. But VarDump package allows to redirect dump() output to another server/port.

Buggregator can listen to this port and display that outpuit on it’s dashboard. This is good for debugging as you can see var dumps, but they will not change server’s response (under the hood dump() function just use symfony/var-dumper that sends data to dump to another API (http://localhost:8100 in our case)).

To make sure you redirect dump() output to the Buggregator, you need to add the following line to the .env file:

dotenv
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=buggregator:9912

For more details, please go to the Buggregator: Symfony VarDumper server.

2. Ray server ​

Ray is very similar to VarDump: it is a debug tool that was created by Spatie. Spatie sells a desktop Ray app that can display data sent to Ray server, but Buggregator can display it for free by listening to the Ray server port.

It’s already preconfigured within config/ray.php:

php
'port' => env('RAY_PORT', env('DOCKER_FORWARD_BUGGREGATOR_PORT', 23517)), // 23517 is a default Ray port

So you can use Ray in your code:

php
ray('hello!'); // like dump()
rd('hello!'); // like dd()

and see the output at the Buggregator dashboard.

More details:

3. Logging channel ​

We have few logging channels like single, daily, slack, etc. (see Laravel logging). Buggregator adds one more channel: socket. It’s already added to the stack logging channel, so you just need to ensure your have in your .env this line:

dotenv
LOG_SOCKET_URL=buggregator:9913

So, now when you Laravel logging, e.g.

php
Log::info('This the the current Member', ['member' => $member]);

it will be displayed on the Buggregator dashboard.

For more details, please go to the Buggregator: Monolog.

4. Email testing ​

When you change an email template or create a new email/notification, you need to test it.

The simplest way to do it is to use the Buggregator email testing feature.

In order to set up your Laravel application to send emails to the Buggregator, you need to add the following lines to your .env file:

dotenv
MAIL_MAILER=smtp
MAIL_HOST=buggregator
MAIL_PORT=1025

Buggregator will catch all emails sent from your application and display them in the dashboard.

But, by default, IxDF-web application doesn't send emails immoderately. Instead, it puts them into a queue to send them after request-response cycle (with or without delay). To instruct your local application to run all jobs inside the request-response cycle, please also change this line:

dotenv
QUEUE_CONNECTION=sync

Now, when you run some code that triggers a Notification send job, the app will do it immediately and send it to the Buggregator’s SMTP server. Code example:

php
$member->notify(new \App\Notifications\Membership\BasicMembership\MembershipCertificateGenerated());

So you can test email templates without sending them to the real email addresses.

Note, after email testing, we recommend revert QUEUE_CONNECTION changes, e.g. to QUEUE_CONNECTION=database (locally).

For more details, please go to the Buggregator: Fake SMTP server.

5. Profiling with XHProf ​

In rare cases you need to profile your code to find performance bottlenecks. You can use XHProf for this purpose. It’s already installed in the buggregator container and XHProf PHP ext already installed in your app container. You need to change the .env file to enable profiling and set the endpoint to send profiling data to the Buggregator server.

dotenv
XHPROF_ENABLED=true
PROFILER_ENDPOINT="http://buggregator:${DOCKER_FORWARD_BUGGREGATOR_PORT}/api/profiler/store"

For more details, please go to the Buggregator: Xhprof profiler.

Other functionality ​

Buggregator has more functionality and adds even more. But it's not covered here for different reasons. Examples:

  • Ray: ATM we don't know any advantages of Ray over dump()/dd().
  • Sentry: we don't Sentry, Laravel has very good exception page out of the box.
  • Inspector: we use Clockwork for similar purposes locally, NewRelic for production.
  • HTTP dumps: we don't know use-cases ATM.
  • SSO: not needed for local development.
  • Webhooks: not needed for local development.
  • Clockwork that we use and that has clock() helper similar to dump().