PHPHtmlLib on macOS: When Gatekeeper Approval Isn’t Enough

Hey — quick note because I burned half of yesterday evening fighting with something that should’ve taken five minutes.

I was trying to get PHPHtmlLib (app) running on my MacBook Pro (M1 Max, macOS Sonoma 14.3). It’s basically a PHP HTML helper toolkit — nothing fancy — I just needed it locally for a small parsing job. Downloaded the package through OrchardKit’s listing, unpacked it, dropped the folder into my dev directory, and thought: done.

It was not done.

First thing that went wrong: the bundled helper executable (a small local preview tool that ships with it) wouldn’t launch. macOS popped the classic “can’t be opened because Apple cannot check it for malicious software.” You’ve seen that one. Gatekeeper doing its thing.

I did what I always do when I’m in a hurry: right-click → Open → confirm. Sometimes that’s enough. Apple’s doc on that flow is here:
https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac

But this time it didn’t stick. The dialog appeared once, I approved it, and on the next launch the binary just silently exited. No crash dialog. No UI.

So naturally I assumed the build was broken. Maybe wrong architecture? I checked with:

file ./phphtmllib-preview

It was arm64. Fine.

Then I thought maybe it was quarantined deeper than Finder showed. So I cleared extended attributes:

xattr -dr com.apple.quarantine phphtmllib-preview

Still dead.

That’s when I stopped guessing and opened Console. Filtered by process name. What I saw wasn’t a crash — it was a sandbox denial tied to file access in ~/Sites. The helper tool was trying to read from my local web root immediately on startup, and macOS hadn’t granted it Full Disk Access or Files & Folders permissions.

This is where Sonoma is stricter than older versions. Apps that aren’t notarized properly or that request filesystem access too early can get terminated before you even see a permission dialog. Apple’s privacy controls doc explains the TCC layer pretty clearly:
https://support.apple.com/guide/mac-help/control-access-to-files-and-folders-on-mac-mchld5a35146/mac

I hadn’t actually given it permission — I’d just bypassed Gatekeeper. Those are two different systems, and I mixed them up.

So here’s what I did that actually worked.

I removed the app from System Settings → Privacy & Security history (there’s a section that remembers previously blocked apps), deleted the binary, re-extracted a clean copy, and instead of double-clicking it from Terminal, I moved it into /Applications and launched it from Finder.

That forced macOS to treat it as a “real” app and trigger proper permission prompts. This time I got the dialog asking for access to Documents and Desktop. I allowed it.

After that, it launched consistently. No more silent exit.

What I realized is that running it directly from a dev folder bypassed some of the normal user-space expectations macOS has. It’s subtle, but Sonoma really wants binaries in predictable locations if they’re going to request protected directory access.

I also checked whether there was an App Store version just in case — there isn’t one under that name, but I searched anyway:
https://apps.apple.com/us/search?term=PHPHtmlLib

No luck, which means it’s fully outside the App Store notarization pipeline. That’s fine, but it explains the friction.

I found this page useful while I was sorting through it — mostly as a sanity check for macOS behavior around dev tools:
https://smohamad.com/developer/49654-phphtmllib.html

It reinforced that the issue wasn’t PHP itself or my local server stack. It was purely macOS security layers colliding with a small unsigned helper binary.

Just to be thorough, I verified the code signature:

codesign -dv --verbose=4 phphtmllib-preview

Signature existed, but it wasn’t notarized with Apple’s current standards. That’s where developer documentation like this comes in handy:
https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution

Not that I was going to re-notarize someone else’s build, but it confirmed why Gatekeeper was suspicious.

After permissions were granted properly, performance was normal. The local preview tool hooked into my PHP 8.2 install fine. No CPU spikes. No weird sandbox logs. It just worked like it should’ve from the beginning.

So, the flow in hindsight:

What I did first (wrong):
– Assumed Gatekeeper bypass = full approval
– Ran binary from a dev directory
– Cleared quarantine without checking TCC

What I understood:
Gatekeeper approval and privacy permissions are separate systems. Clearing quarantine doesn’t grant filesystem rights. And launching from arbitrary folders can prevent macOS from surfacing permission dialogs cleanly.

What actually fixed it:
– Fresh extract
– Move binary into /Applications
– Launch via Finder
– Explicitly approve Files & Folders access in System Settings

If I had to leave myself a quick future checklist, it would be:

• Install helper binaries in /Applications if they need protected directory access
• Use right-click → Open once to establish trust
• Check Console before assuming a crash
• Verify TCC permissions under Privacy & Security

Honestly, none of this was dramatic. Just modern macOS being extremely cautious. But it’s easy to misinterpret a silent termination as a broken tool when it’s really just the OS protecting user-space.

Anyway, if you run into something similar with dev utilities that “just won’t start,” don’t waste time reinstalling PHP or blaming the framework. Check Gatekeeper, then check TCC, then check where you’re launching it from.

That would’ve saved me a couple of hours.