Once upon a time, roughly before 2012, PHP's native IMAP worked in GMail by default. It still will work, but you have to reduce security for your GMail account. I wrote a short blurb about this below.
Using OAUTH is doable, but it's somewhat painful. Hopefully this will reduce the pain.
Go to the Google developer's console / Google APIs. My dev / API account is part of my main GMail address / main Google account. You probably have to do something else, though. I don't remember how I got the dev stuff activated. For now, I don't want to spend the time doing that again, so hopefully you'll figure that out.
Once in your account, go to the Google APIs "IAM & Admin" menu, then "All Projects," then "CREATE PROJECT." I believe project names need to be unique through all Google projects, not just yours. While you think about a spiffy name, for now just create an obscure name to play with. These project steps aren't hard, so doing them again doesn't take long.
Creating a project takes a few seconds (6-ish). Then, you'll be redirected and you'll see your new project name in the upper left, to the right of "Google APIs."
In the center middle, go to OAuth consent screen. You have to give your project a "Product name shown to users" and then save that. The text you enter is what you'll see in several steps when you authorize your project via the web and your Google account. You do NOT need to fill out anything else for our purposes.
Then go to "Credentials" on the left. (Despite verbiage to the contrary, you do NOT need to enable a specific API for our purposes.) Then "Create Credentials" of the type "OAuth client ID."
Pick "Application type" "Other" and accept the default name or give it a name, then "Create." (The "other" type seems weird, yes, but trust me. There might be other options, but there are also options that will NOT work such as "Web application" will NOT work.
When you hit "Create," you'll get a popup. You do NOT need to save this now. Just hit "OK."
You'll now be looking at a list of "OAuth 2.0 client IDs." The client ID name is a link, although it's not blue until you hover. Click on the name, and you'll see the "Client ID" and "Client secret" again.
Download oauth2.py. Note that the PHP script does NOT do the same thing, and it's not what we want for now.
(You'll have to install Python, of course, if you don't already have it.)
29 lines down, oauth2.py explains how to run it. I'd imagine you can run it with the "python" command, but it Linux, I'm finding it much easier to give the script execute permission, then you may need to use "$ ./oauth2.py" if "." is not in your path, where the quotes aren't "for real" and $ is the Linux prompt.
As it shows from line 29, run it like this:
oauth2 --user=xxx@gmail.com \
--client_id=1038[...].apps.googleusercontent.com \
--client_secret=VWFn8LIKAMC-MsjBMhJeOplZ \
--generate_oauth2_token
When you run it, you'll be given a URL to go to. Note that the Python script is waiting for input. When you go to the URL and "Allow," you'll get a ~45 character string to enter into the Python script.
When you enter that ~45 char string, you'll get an "Access Token" and "Refresh Token." I'm pretty sure the refresh token is important beyond our testing, but I am ignoring it for now. Save the Access Token someplace safe--"safe" such as not on your public web site. (Note that you can revoke your application's access to GMail fairly easily, thus making the token moot. I'll come back to that eventually.)
If you don't already have it, install "composer" (for PHP). In Ubuntu, it's a command to install like any other via apt-get.
You'll now want to pick a directory / folder to house your soon-to-be-created PHP script and zend-mail and such. Create and / or go to that directory.
At the command prompt in your directory, run "composer require zendframework/zend-mail" (without the quotes). When it's done, you should have the files "composer.json," "composer.lock," and a "vendor" directory.
Now create the following PHP script and substitute 1. your email address, 2. the access token you saved, and 3. modify the "vendor" path as needed
Assuming you have at least one email in your inbox, run the PHP script (i.e. $ php imap.php ). You should see the first subject line in your inbox.
Note that the access token lasts an hour. After that, I believe you'll need the refresh token, but I haven't gotten that far in the process.
Note that the Google example uses _ rather than \ for Zend\Mail\... That caused me a great deal of grief. This is autoload stuff that I don't entirely understand.
Also note that the example uses boolean "true" rather than "ssl." That caused me some grief.
The base64_encode line comes out of the example and can be deemed "magic."
As show in the oauth2.py documentation, do this:
oauth2 --generate_oauth2_string --user=xxx@gmail.com \
--access_token=ya29.AGy[...]ezL
You'll get a longer string, an "OAuth2 argument." Save that somewhere safe.
From the Linux (or other) command line, run:
openssl s_client -crlf -connect imap.gmail.com:993
Once Gmail connects, run:
command1 AUTHENTICATE XOAUTH2 [OAuth2_argument]
where [OAuth2_argument] is the string you created from oauth2.py just above. "command1" is arbitrary. I believe you could just use a period or many inputs.
The output should be a "CAPABILITY" list and then, "command1 OK example@gmail.com authenticated (Success)"
I wrote quite a bit on IMAP years ago. Much of it is still valid.
In PHP, you can substitute the Oauth argument for the Access token as below. It makes for shorter code:
Note that oauth2.py gives an example of using the refresh token, and I'm sure you can read all about it. I may include them here one day.
In addition to the following, IMAP needs to be enabled in your GMail settings under "Forwarding and POP/IMAP."
To use PHP (native) IMAP with a username and password rather than OAUTH, starting from your GMail webmail, go to the Google account "circle" with your initial or picture, on the top right of the screen, then "My Account." Go to "Connected apps & sites" on the left, then go to "Allow less secure apps" towards the bottom right. Turn the switch "on" and username/pwd will work. You'll probably want to turn that off when you're done.
For search / reference purposes, this is what that "feature" says:
Allow less secure apps: [OFF or ON]
Some apps and devices use less secure sign-in technology, which could leave your account vulnerable. You can turn off access for these apps (which we recommend) or choose to use them despite the risks.