- Joined
- Jul 25, 2024
- Messages
- 142
- Thread Author
- #1
Introduction
One of the most-asked questions in the XenForo Dev Section is: How do I access data from XenForo in other applications? Generally speaking, there is two ways you can go about this: If your application is in a different language than PHP, or resides on a different server, you can utilize the built-in API to access most data, and push and pull content from and to your XenForo installation. If you're on the same server, and your other application is also running PHP, you can leverage the full power by launching XenForo and gain access to all its functions and objects.
This guide is meant to give a brief overview over the second option. If you're searching for more information on how to use the XenForo API, here's some further reads for you:
As a short mention upfront: To follow this method, it is recommended to have a good understanding of PHP, as well as some basic knowledge of the XenForo framework. If you've read through the Dev Documentation and ideally followed the Let's build an add-on guide, you may have the basics ready to proceed.
Before proceeding, keep in mind that adding an entire framework to your application can put some strain on available resources. Unless you plan to make use of it on at least most requests, think about how you can load it only when it is required, rather than always.
Launching the XenForo app
Launching XenForo is simple. All you need is the relative path to your XenForo root directory, as well as the following code snippet:
PHP:
$dir = '<your_xenforo_root_directory_path>';
require($dir . '/src/XF.php');
\XF::start($dir);
Simple as that, you've started the XenForo application, and gained access to all methods and objects.
Accessing data
To read and write to the database, you can now use the Entity Manager via \XF::em(), as well as the Database via \XF::db(). Unless specficially required, using the entity manager is the preferred way to go. It will provide you with ready made entity objects that you can manipulate and save, as well as handling all 3rd party add-ons, and pre/post-save events automatically for you. If you're not yet familiar with the entity management system, make sure to give the dev documentation section a read.
There is also a few handy shortcuts available to load certain parts:
To access the current visitor, you first have to make sure, that your application has access to the same cookies that XenForo has. If you're running it on a different subdomain, make sure to configure your XenForo application, so that it shares cookies with your custom application.
Once you verified that, you can load the XenForo visitor object at any time with the following shortcut:
Advanced code
Until now, you've learned how to load your XenForo application and perform basic read and write operations. Below, you find some more advanced examples and explanations.
Templates
The XenForo templater allows you to render any template and macro, public, admin or email. All you need is to initialize it first, and then pass the required data into each template or macro that you are attempting to load.
Before you get started using the templater, you first need to initialize the global parameters:
With the templater prepared, you can now render templates and macros as you want:
Embedding your own templates into the XenForo wrapper
To generate the XenForo wrapper, you simply need to render the PAGE_CONTAINER template, with a few extra parameters.
Keep in mind, that this will only give you a ready-rendered view. You still need to generate and send back an appropriate response to the users request yourself. If you don't want to do this, you may be better off writing an add-on, and have the controller handle your application code instead.
Depending on your setup, you may also need to handle additional situations like relative URLs, and passing additional page parameters to the public template. This is beyond the scope of this quick overview and thus not covered.
Services
Services are usually used to handle more complicated processes, commonly to process user input into new entities, or modify existing entities in a more complex way than a simple save. To use a service, you first need to gather all required entities (and input, where required). Then you can generate your service with the following code:
Which entities (and how many) are required, depends on the service to choose. Depending on what service you use, you then usually have to call additional methods on the obtained entity object, to pass input data, and finally execute the service. How this is done, depends on the service in question.
Controllers
When you need to mimic a XenForo controller action, or want access to a result of a controller flow, you can generate your own controller and execute the method in question. In the following example, we'll execute the view action of the XF:Thread controller, to render a thread view. You will first need to generate a request object and parameter bag that fits your required controller action. This is as simple as:
Once you possess the right parameter bag and request objects, you can generate a controller and use phps reflection methods, to execute the right actions:
If you want to execute a controller method that is not an action but instead a private method, you can save yourself the trouble of generating the parameter bag and request objects, and directly execute the method:
Final words
This should give you a quick overview on how to launch the XenForo application in your custom code, and perform basic and advanced tasks with the framework. From there on out, most tasks can be treated as if you lived in the XenForo context, and thus most solutions from the Dev forum section can be applied, ususally either unmodified or in a slightly modified variant.
Keep in mind that bringing two applications together is not an easy task, and shouldn't be taken lightly. If you struggle, consider hiring on an experienced developer to write the code for you, to ensure you don't open any loopholes or attack vectors in your environment. Safety should always be more important than minor functionality boons.
One of the most-asked questions in the XenForo Dev Section is: How do I access data from XenForo in other applications? Generally speaking, there is two ways you can go about this: If your application is in a different language than PHP, or resides on a different server, you can utilize the built-in API to access most data, and push and pull content from and to your XenForo installation. If you're on the same server, and your other application is also running PHP, you can leverage the full power by launching XenForo and gain access to all its functions and objects.
This guide is meant to give a brief overview over the second option. If you're searching for more information on how to use the XenForo API, here's some further reads for you:
- XenForo Rest API - Official Documentation
- XenForo Rest API - Official Endpoint Documentation
- xfapi-php - An open source XenForo API consumer library for PHP
As a short mention upfront: To follow this method, it is recommended to have a good understanding of PHP, as well as some basic knowledge of the XenForo framework. If you've read through the Dev Documentation and ideally followed the Let's build an add-on guide, you may have the basics ready to proceed.
Before proceeding, keep in mind that adding an entire framework to your application can put some strain on available resources. Unless you plan to make use of it on at least most requests, think about how you can load it only when it is required, rather than always.
Launching the XenForo app
Launching XenForo is simple. All you need is the relative path to your XenForo root directory, as well as the following code snippet:
PHP:
$dir = '<your_xenforo_root_directory_path>';
require($dir . '/src/XF.php');
\XF::start($dir);
Simple as that, you've started the XenForo application, and gained access to all methods and objects.
Accessing data
To read and write to the database, you can now use the Entity Manager via \XF::em(), as well as the Database via \XF::db(). Unless specficially required, using the entity manager is the preferred way to go. It will provide you with ready made entity objects that you can manipulate and save, as well as handling all 3rd party add-ons, and pre/post-save events automatically for you. If you're not yet familiar with the entity management system, make sure to give the dev documentation section a read.
There is also a few handy shortcuts available to load certain parts:
- \XF::finder('My:Finder') will load a specific finder for you.
- \XF::repository('My:Repository') will load a specific repository for you.
To access the current visitor, you first have to make sure, that your application has access to the same cookies that XenForo has. If you're running it on a different subdomain, make sure to configure your XenForo application, so that it shares cookies with your custom application.
Once you verified that, you can load the XenForo visitor object at any time with the following shortcut:
Advanced code
Until now, you've learned how to load your XenForo application and perform basic read and write operations. Below, you find some more advanced examples and explanations.
Templates
The XenForo templater allows you to render any template and macro, public, admin or email. All you need is to initialize it first, and then pass the required data into each template or macro that you are attempting to load.
Before you get started using the templater, you first need to initialize the global parameters:
With the templater prepared, you can now render templates and macros as you want:
Embedding your own templates into the XenForo wrapper
To generate the XenForo wrapper, you simply need to render the PAGE_CONTAINER template, with a few extra parameters.
Keep in mind, that this will only give you a ready-rendered view. You still need to generate and send back an appropriate response to the users request yourself. If you don't want to do this, you may be better off writing an add-on, and have the controller handle your application code instead.
Depending on your setup, you may also need to handle additional situations like relative URLs, and passing additional page parameters to the public template. This is beyond the scope of this quick overview and thus not covered.
Services
Services are usually used to handle more complicated processes, commonly to process user input into new entities, or modify existing entities in a more complex way than a simple save. To use a service, you first need to gather all required entities (and input, where required). Then you can generate your service with the following code:
Which entities (and how many) are required, depends on the service to choose. Depending on what service you use, you then usually have to call additional methods on the obtained entity object, to pass input data, and finally execute the service. How this is done, depends on the service in question.
Controllers
When you need to mimic a XenForo controller action, or want access to a result of a controller flow, you can generate your own controller and execute the method in question. In the following example, we'll execute the view action of the XF:Thread controller, to render a thread view. You will first need to generate a request object and parameter bag that fits your required controller action. This is as simple as:
Once you possess the right parameter bag and request objects, you can generate a controller and use phps reflection methods, to execute the right actions:
If you want to execute a controller method that is not an action but instead a private method, you can save yourself the trouble of generating the parameter bag and request objects, and directly execute the method:
Final words
This should give you a quick overview on how to launch the XenForo application in your custom code, and perform basic and advanced tasks with the framework. From there on out, most tasks can be treated as if you lived in the XenForo context, and thus most solutions from the Dev forum section can be applied, ususally either unmodified or in a slightly modified variant.
Keep in mind that bringing two applications together is not an easy task, and shouldn't be taken lightly. If you struggle, consider hiring on an experienced developer to write the code for you, to ensure you don't open any loopholes or attack vectors in your environment. Safety should always be more important than minor functionality boons.
