Composer Help, Please

[DamnYankee]

Hi All, Newb here - DON"T RUN AWAY YET!

I installed Apache 2.4 and PHP 8.14.15 on a Windows 11 machine to be used as a dev server.  I need to add PHP/Mailer to a site and from what I gather, Composer is the best choice.  I know Composer is a dependency manager, but I have no idea of how it works - even after reading the documentation four times.

My dev folders are remote from Apache's htdocs folder.  I would like Composer to be Global for any site in development (remote folder or htdocs folder).  The installation instructions are ambiguous to me, unfortunately. 

• Does Composer go anywhere and then has a config file pointing to where PHP is and where the dev site root is? 
• How is that configured?
• Does it load the latest and greatest Composer file automatically upon start-up?
• Speaking of start-up, is it a service that continuously runs in the background or do I use the Command Prompt?
• What about code like PHP?Mailer; does it update that to the latest release or is that a manual thing?
• Finally (and perhaps obvious), once Composer is installed, is PHP/Mailer installed using the Command prompt?

I was going to take a stab at installing it, but two things stopped me dead in my tracks - one was a mention of the hardship of upgrading and the other if (when) I botch the install; the problem of removing all trace of Composer for a fresh install.

Thanks!

[gizmola]

As you noted, Composer is a dependency management tool.  In that way it is not different from tools for other languages like npm for javascript.  

The best way to handle this is to install composer globally on your system.  Composer has a windows installer here:  https://getcomposer.org/Composer-Setup.exe

Download and run it, and it should set up composer for global use on your system.

After installation you should be able to run this from any directory.

composer -V

 

Once installed, open a terminal and change to the directory of your project. 

Ultimately, in order to understand modern PHP development you need to understand namespaces, and use them in your own code. 

You have a few options, but the best one is to run "composer init" in this directory and answer the questions it prompts you for.  

The first question will be a prompt for your "vendor"/"package".   It's not important for your own project what you make these names, but you want to use some sort of name that identifies you.  If you have a github account, your github name would be a good choice.  This will be used along with the package name you provide as the namespace for any classes you create.  You will place these inside the {project_dir}/src directory that will be created by composer.

You do not need to add dependencies at this point, so just answer no to those questions.  Once completed, it will have created a simple composer.json and composer.lock file, as well as the /src directory.

At this point you are ready to add any libraries you want to use.  You'll find similar instructions for most libraries, but to install phpmailer, again from the project directory root you will run:

composer require phpmailer/phpmailer

You should note that composer will create a vendor directory where all libraries (and any dependent libraries) are placed and referenced.

You want to keep both the composer.json and the composer.lock files in your project source code, as you use these to replicate your project from development to production.

Once you have things setup read the instruction for phpmailer in their github repo:  https://github.com/PHPMailer/PHPMailer

Notice that any of your scripts that actually are executed need to include the autoloader file generated, as illustrated in their documentation.

Once piece of advice:  have a subdirectory in your project where these "controller" scripts go.  A controller script is any script that will be directly referenced from the webroot.  This is far beyond a simple introduction to this, but most projects utilize a "front controller"   (ie. index.php) through which all routing and control passes.  All the well known MVC frameworks use this pattern to bootstrap apps, so that everything passes through this front controller script.  If you manage something like that for your app you vastly improve security and make things simpler and easier to manage, and in particular only need the autoloader to be required in that one script, but again it just needs to be required in any script that is under the webroot.  You do not want all your project files or the vendor directory or the src directory to be inside the webroot.

So for this to work, you will also want to create a directory in your project directory, most commonly named "public".  You then make  {project_dir}/public your webroot for your development site and ultimately for your production version and put things that should be available from the webroot (including static files like css, js etc.) in subdirectories under public.

While there is a lot more to this topic, hopefully you have enough now to get started.

 

[DamnYankee]

Thank you for the very well-presented instructions.  

I do have three questions before I continue with an init command:

1. In your explanation of PHPMailer, you mentioned installing it in the Webroot.  Is the webroot of my host the public folder or the folder in which it resides?
2. And, if it is the public folder, should my dev files also be nested inside a folder named public because of references?
3. Does this apply only to PHPMailer or should it apply to any files installed by Composer, including Composer itself?

Thanks,

John

Edited December 29, 2025 by DamnYankee

[gizmola]

8 hours ago, DamnYankee said:

Thank you for the very well-presented instructions.  

I do have three questions before I continue with an init command:

1. In your explanation of PHPMailer, you mentioned installing it in the Webroot.  Is the webroot of my host the public folder or the folder in which it resides?
2. And, if it is the public folder, should my dev files also be nested inside a folder named public because of references?
3. Does this apply only to PHPMailer or should it apply to any files installed by Composer, including Composer itself?

Thanks,

John

Excellent questions, hopefully I'll clarify.

These days, most projects have a "project" name.  So I'm assuming you will follow that convention.  It doesn't matter what it is, but as most people will use git and a git remote like github or bitbucket to push their code to, usually the name will be whatever the github repo name is.  That is totally up to you, but for this example, I'm going to assume the name is "mailer_site".

I tend to develop projects on my workstation within a "Projects" directory under my home user, and I will make a subdirectory under that for each project, although sometimes if I have groups of projects I'll use multiple nested folders.  

It really doesn't matter how or where you do this, although as a windows user I would advise that you avoid creating directory names with spaces in them, or using mixed case.  If you want to have an space in the name, use an underscore as in my example.  So your project directory path in these  examples assume the local username is "gizmo" and so will be:

# Path to projects
C:\Users\gizmo\Projects

# Path to new project
C:\Users\gizmo\Projects\mailer_site

In your terminal you want to CD into this directory to run your "composer init". 

Personally, I am a big fan of installer systems for most local installations.  I use "brew" for the mac, and for windows "Chocolatey".  I didn't mention this, but a great way to install composer is to enter an administrator terminal and run "choco install composer".  If all goes as plan, you shut that terminal, open your user terminal and composer should be ready to use globally.  If you haven't looked at it, check out Chocolatey.  There are others like winget that serve a similar purpose.  I install most if not all developer languages and tools, editors etc using the chocolatey cli, as it takes care of a many annoying details and makes upgrades or uninstalls easy.

Commands like "pwd" are useful in the terminal to verify the path.

Thus all the "meta files" will be in the root of this project directory.

If you follow the steps I mentioned, in this directory you will have opened the terminal (non administrator terminal), and created the directory for your project, and used cd to enter it.  Now run composer.  One other detail I didn't mention, is that for "minimal stability" enter "stable".    When complete you should see something like this 

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        12/29/2025   7:06 PM                src
d-----        12/29/2025   7:07 PM                vendor
-a----        12/29/2025   7:07 PM            374 composer.json
-a----        12/29/2025   7:07 PM           4274 composer.lock

Notice that composer made the src and vendor directories.  (If you look in vendor you'll see the phpmailer lib directory structure and the autoload.php file that composer generated, and you will want to require for "runable" scripts.

The composer.json file should look something like this:

{
    "name": "gizmo/mailer_site",
    "type": "project",
    "autoload": {
        "psr-4": {
            "Gizmo\\MailerSite\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Gizmola",
            "email": "gizmola@...."
        }
    ],
    "minimum-stability": "stable",
    "require": {
        "phpmailer/phpmailer": "^7.0"
    }
}

At this point, you want to add additional directories.  Most projects follow a skeleton the same or similar to the one Described here:  https://github.com/php-pds/skeleton?tab=readme-ov-file

That project readme has a nice table showing additional folders/directories you may or may not want to add.  For example, people who create unit tests will use the /tests folder and create additional folders beneath it. 

Obviously that is way beyond the scope of your question.  If this is intended to be a cli tool, you might want to have "bin" directory, and some projects might want to have a var directory which often will have subdirectories of log and or cache, for generated files (common to template libraries which compile templates to php scripts), and other things.  The most important concept however, is that the webroot of the running webserver will be the {project}/public directory!

A lot of people use docker these days and will often have additional files and directories off the project root, and meta files like a docker-compose.yml file.  For git you will want a .gitignore, and many projects also will include .env files here (although you don't want to save those in your repository).

At minimum, I would add these folders to the project:

mkdir public
mkdir config
mkdir tests

# Should see something like this if you DIR


    Directory: C:\Users\gizmo\Projects\mailer_site


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        12/29/2025   7:21 PM                config
d-----        12/29/2025   7:22 PM                public
d-----        12/29/2025   7:06 PM                src
d-----        12/29/2025   7:22 PM                tests
d-----        12/29/2025   7:07 PM                vendor
-a----        12/29/2025   7:07 PM            374 composer.json
-a----        12/29/2025   7:07 PM           4274 composer.lock

 

So your "webroot" will something like:  C:\Users\you\Projects\mailer_site\public

The web/document root for your webserver is the setting that needs to specify this directory.

In the "public" folder, you should put other folders that need to be in webspace.  Like any "html" project these are typically folders like:  css, js, image etc. 

Inside this folder, as an example, you will start with an "index.php" file.

What you will have is then some code like this:

Notice all the things that are NOT beneath the webroot including:  any of your meta/config files, configuration files like .ini or any other files that might have credentials or configuration info.  Your application classes or function libraries (which should be inside the src directory).  Nor will the libraries you've required (which are in the vendor directory).  You can refer to any of these files as needed using require, although libraries and classes you create in the src directory will be automagically loaded as needed using proper php namespaces, but the autoloader will resolve for you.

 

So here is a base index.php file to start you off:

<?php
    // public/index.php
    use PHPMailer\PHPMailer\PHPMailer;
    use PHPMailer\PHPMailer\SMTP;
    use PHPMailer\PHPMailer\Exception;

    define('PROJECT_HOME', dirname(__DIR__));
    require(PROJECT_HOME . '/vendor/autoload.php');

    // Right out of the phpmailer docs
    $mail = new PHPMailer(true);

    //etc...

 

You might notice the constant definition as that is a convenient way to generate relative paths.  You can also refer to files in config this way using "require(PROJECT_HOME . '/config/settings.php'); or whatever else you might need to load or refer to on the filesystem.  This way you don't hardcode paths to a specific installation.

At this point there is not much more to it, again if you understand how PHP namespaces work.  Just to demonstrate how you might add a class of your own, relative to the PSR-4 convention which has associated the namespace of "Gizmo\\MailerSite\\": "src/", any folder you create within the src directory will have the namespace of "Gizmo\Mailersite".  

If you create a subdirectory the namespace will then be extended using that name, however you can simply place a class file inside the directory.  

In this example, if you create a class in the src directory with the name "MyApp.php" with these contents:

<?php
namespace Gizmo\MailerSite;

class MyApp {
    private string $name;

    public function __construct(string $name) {
        $this->name = $name;
    }
    
    public function getName() {
        return $this->name;
    }
}

 

You can then refer to this class using the namespace configured in the composer.json.

<?php
    // public/index.php
    use PHPMailer\PHPMailer\PHPMailer;
    use PHPMailer\PHPMailer\SMTP;
    use PHPMailer\PHPMailer\Exception;
    use Gizmo\MailerSite\MyApp;

    define('PROJECT_HOME', dirname(__DIR__));
    require(PROJECT_HOME . '/vendor/autoload.php');

    $app = new MyApp('My Mailer App');

    // Right out of the phpmailer docs
    $mail = new PHPMailer(true);

    echo $app->getName();

 

I should note that you do not have to go so far as to supply a full namespace, particularly if the application is going to be self contained.  Many projects (and frameworks will use the convention of associating /src contents with the "App" namespace, as in:

    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },

 

So in that case, the same class would be referred to via the namespace of:

use App/MyApp;

 

Assuming you have a local cli php version installed with composer, you could run this as a simple test using php's built in webserver.  You would cd into the public directory and start the development server:

cd public
php -S localhost:8000

Open localhost:8000 with your browser and the code provided should work with no errors and display "My Mailer App".

[DamnYankee]

Again, a clear and concise solution - thank you!