Building a PHP application is one thing. Packaging it so another person can install it on their own hosting environment is something entirely different.

While preparing several self-hosted PHP applications for commercial distribution, I encountered issues that were easy to overlook during development but became important when testing the actual customer installation packages.

Here are five practical lessons from that process.

1. Never Assume Your Application Will Be Installed at the Domain Root

One of the most frustrating installation issues involved applications that worked perfectly at:

https://example.com/

But behaved incorrectly when installed at:

https://example.com/myapp/

The installation might complete successfully, yet the browser would show missing CSS, broken links, or a 404 error after login.

The cause was often a hardcoded URL or a redirect that assumed the application lived at /.

For example:

header('Location: /login'); 

This sends the browser to:

https://example.com/login

Even when the application is installed inside /myapp.

A better approach is to establish the application's base URL during installation and consistently use it when generating links.

For example:

$config = [ 'app_url' => 'https://example.com/myapp', ]; function app_url(string $path = ''): string { global $config; return rtrim($config['app_url'], '/') . '/' . ltrim($path, '/'); } header('Location: ' . app_url('login')); exit; 

This is a simplified example; production code should validate the configured base URL and handle URL generation consistently throughout the application.

Lesson: Test both domain-root and subfolder installations before releasing a customer ZIP.

2. Required Directories Must Actually Exist in the ZIP

Another problem came from missing directories.

An installer expected folders such as:

config/ storage/ storage/cache/ storage/logs/ 

But ZIP files do not always retain empty directories.

As a result, an installation check could report that a required folder was missing or not writable.

The solution was to include placeholder files such as .gitkeep where necessary.

For example:

storage/ cache/ .gitkeep logs/ .gitkeep 

The installer should also check whether the application can create the required files.

A basic check might look like this:

$directory = __DIR__ . '/storage/cache'; if (!is_dir($directory)) { throw new RuntimeException( 'Required storage directory is missing.' ); } if (!is_writable($directory)) { throw new RuntimeException( 'Storage directory is not writable.' ); } 

This check should be performed before creating application configuration or activating a license.

Lesson: Test the extracted ZIP package, not only the development directory.

3. License Activation and Verification Are Different Operations

For commercial self-hosted software, a licensing system generally needs to answer two different questions:

Activation: Is this purchase authorized to register this installation?

Verification: Is the installation still authorized after activation?

Activation typically happens during installation.

Verification happens periodically after installation.

An example activation request might include:

{ "purchase_code": "CUSTOMER-PURCHASE-CODE", "software_id": "EXAMPLE-SOFTWARE-ID", "activation_type": "domain", "activation_identifier": "example.com" } 

These are illustrative values, not real credentials.

For a domain-based license, the server can enforce an installation limit and associate the purchase with an authorized domain.

The application must also store enough local information to recognize an already activated installation.

One important implementation decision is to avoid storing a purchase code in plain text unnecessarily.

Depending on the architecture, an encrypted local credential or server-issued verification token can be used.

If storing encrypted credentials locally, encryption keys should be generated securely and kept separate from the encrypted data.

Lesson: Activation registers an installation. Verification maintains its licensing state. Both need a clearly defined security model.

4. A Temporary License Server Outage Should Not Disable Legitimate Customers

Imagine a customer has purchased and activated an application successfully.

A few weeks later, the licensing server experiences a short network interruption.

Should the customer immediately lose access to their software?

Usually, that would create an unnecessarily poor experience.

A more resilient licensing design distinguishes between:

  • An explicitly revoked or suspended license.
  • A license that has been successfully verified.
  • A temporary network failure that prevents verification.

A temporary connection error should not automatically be treated as license revocation.

One approach is to maintain a last-known-valid license state and allow an appropriately limited verification grace period.

For example:

if ($verificationSucceeded) { // Update the last verified timestamp. } if ($temporaryNetworkFailure) { // Apply the documented offline grace policy. } if ($licenseExplicitlyRevoked) { // Enforce the license restriction. } 

This is conceptual pseudocode, not a complete license implementation.

The grace-period duration and enforcement behavior should match the application's licensing terms.

Lesson: Network failures and explicit license rejection are fundamentally different events.

5. The Final Customer ZIP Is the Product

Perhaps the biggest lesson is that successful development tests are not enough.

An application may work correctly on the developer's server because that server already contains configuration files, folders, database tables, or environment settings created during development.

The customer receives only the ZIP.

That is what must be tested.

Before releasing a PHP application, I now prefer to check:

  1. Extract the ZIP into a completely fresh folder.
  2. Confirm the required directories are present.
  3. Create a new empty database.
  4. Run the installer using the same instructions customers receive.
  5. Test the application at both a domain root and a subfolder.
  6. Verify that CSS, JavaScript, redirects, and login work.
  7. Test license activation with a valid purchase code.
  8. Confirm the application's licensing state after installation.
  9. Remove the installer when instructed.
  10. Confirm the application still works after logging out and signing in again.

PHP syntax validation and ZIP integrity checks are also useful, but they cannot replace a real installation test.

Lesson: Don't only test your source code. Test the exact package your customer will download.

Final Thoughts

Self-hosted software has an advantage: customers can run applications on their own hosting infrastructure and maintain more direct control over their installation.

But that flexibility creates additional responsibilities for developers.

Different PHP versions, hosting configurations, URL structures, filesystem permissions, and database environments can expose problems that never appeared during development.

I've found that treating installation, licensing, documentation, and packaging as core parts of the product makes the entire development process more reliable.

The next time I develop a PHP application, I'll test its installation experience much earlier instead of leaving it until the end.

What has been your most frustrating issue when deploying a self-hosted PHP application?

AI assistance disclosure: This article was drafted with AI assistance and reviewed against real development and installation experiences. The code examples are illustrative and should be adapted and tested before production use.