Best way to include & use php classes in Magento

Best way to include & use php classes in Magento

July 27, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Best way to include & use php classes in Magento

Magento Best Practices: Including External PHP Classes Across Multiple Templates

Are you looking to integrate an external PHP class like the Mobile Detect library into your Magento website? You’re not alone! Many developers struggle with the best way to include and use PHP files across multiple templates within Magento’s complex folder structure.

Let’s dive into some best practices for including external PHP classes in Magento, step by step.

Understanding Magento Templates and Subtemplates

In Magento, you typically have a main template (like main-template.phtml) that serves as the base layout. Inside this main template, you can insert sub-templates like header.phtml, footer.phtml, etc., using the getChildHtml() method.

Here’s how your folder structure might look:

app/design/frontend/
└── your_package/
    ├── your_theme/
    │   ├── templates/
    │   │   ├── page.xml
    │   │   ├── main-template.phtml
    │   │   └── header.phtml
    │   └── web/
    │       ├── css/
    │       └── js/
    └── layout/
        └── your_package.xml

Including External PHP Classes in Magento

When you want to include an external PHP class like the Mobile Detect library, you have a few options:

1. Include the File Directly in Each Template

You can directly include the Mobile_Detect.php file inside each template where you need it. This is simple but not recommended for larger projects because it duplicates code and makes maintenance harder.

// main-template.phtml
<?php
include_once 'Mobile_Detect.php';
$detect = new Mobile_Detect();
?>

2. Place the File in Magento’s Library Folder

Magento has a lib folder where you can place external PHP libraries:

app/code/core/Mage/
└── lib/
    └── your_library/
        └── Mobile_Detect.php

You’ll need to ensure that this folder is included in your project’s .gitignore file if it’s not part of the library itself.

The best practice is to create a Magento helper class to handle the inclusion and usage of external libraries. This keeps your templates clean and separates business logic from presentation:

Create a new helper in app/code/local/YourNamespace/YourModule/Helper/Data.php:

<?php

class YourNamespace_YourModule_Helper_Data extends Mage_Core_Helper_Abstract {

    public function isMobile() {
        include_once Mage::getBaseDir('lib') . '/your_library/Mobile_Detect.php';
        $detect = new Mobile_Detect();
        return $detect->isMobile();
    }
}

Then, you can call this helper in your templates:

// main-template.phtml
<?php echo Mage::helper('yourmodule')->isMobile() ? 'mobile' : 'not mobile'; ?>

Conclusion

Including external PHP classes in Magento is a common requirement. The key is to separate business logic from presentation and keep your templates clean.

The recommended approach is to create a helper class that handles the inclusion and usage of external libraries. This makes your code more maintainable, readable, and easier to manage across multiple templates.

Remember to place any external PHP files in Magento’s lib folder or a dedicated library folder within your custom module for better organization.

For more advanced use cases and best practices, check out our comprehensive guide on working with Magento helpers.

Happy coding! Let me know if you have any further questions.

Themes JavaScript

Our network