pdf_fit — Smart PDF optimization toolkit

A PHP 8.1+ CLI + API for compressing, resizing, and analyzing PDFs with Ghostscript, plus a gated web dashboard for Tech & Stream workflows.

Product scope

• CLI: bin/pdf_fit provides smart, compress, optimize, extreme, resize, batch, and server modes.
• API: public/index.php exposes a JSON API for PDF processing.
• Dashboard: password-protected UI with the Tech & Stream “Agent Freelance” cockpit.
• Plugins: metadata extraction and thumbnail generation hooks.

Prerequisites

• PHP 8.1+
• Composer
• Ghostscript (gs) for compression/thumbnail generation
• Optional: Poppler pdfinfo for metadata enrichment

Install

composer install
chmod +x bin/pdf_fit bin/job_apply

Run

CLI

php bin/pdf_fit smart tests/Fixtures/example.pdf
php bin/pdf_fit compress report.pdf --quality=55 --dpi=150
php bin/pdf_fit resize brochure.pdf --width=1080 --height=1920
php bin/pdf_fit batch ./statements --mode=smart
php bin/pdf_fit server --host=0.0.0.0 --port=8080 --docroot=public

Job application helper

php bin/job_apply docs/job_post.txt
php bin/job_apply docs/job_post.txt --json

Project Velocity sprint plan generator

php bin/project_velocity --blueprint=docs/blueprint.txt --sprint=1 --output=docs/sprint_1.md

API

php -S 127.0.0.1:8080 -t public
# POST multipart/form-data:
# - pdf: file upload
# - mode: smart|compress|optimize|extreme|resize
# - quality/dpi/width/height: optional overrides

Example:

curl -F pdf=@tests/Fixtures/example.pdf -F mode=smart http://127.0.0.1:8080

Configuration

Use config.php for persistent config or environment variables for quick overrides. Copy .env.example as needed.

Setting	Description
PDF_FIT_OUTPUT_SUFFIX	Suffix appended to exported PDFs
PDF_FIT_THUMBNAIL_QUALITY	JPEG quality for thumbnail plugin
PDF_FIT_LOG_FORMAT	text or json
PDF_FIT_DEBUG	1 to include stack traces in CLI errors
PDF_FIT_DASHBOARD_PASSWORD	Required for dashboard access

Troubleshooting

• Ghostscript not found: install gs and ensure it is on PATH. The CLI warns and returns the original file if missing.
• No PDFs in batch: batch mode exits with a warning if the directory has no .pdf files.
• Dashboard locked: set PDF_FIT_DASHBOARD_PASSWORD or config/security.local.php.

Security notes

• The dashboard must be protected via PDF_FIT_DASHBOARD_PASSWORD before deployment.
• Do not expose public/ without a password gate in production environments.

Repository layout

bin/
  pdf_fit
  job_apply
config/
public/
src/
  Api/
  Batch/
  Cli/
  Core/
  JobAgent/
  Plugins/
  Security/
  Support/
  AgentFreelance.php

Contribution workflow

1. Fork and create a feature branch.
2. Install dependencies: composer install.
3. Run checks:
   • composer lint
   • composer test
4. Open a PR with a clear summary and screenshots when UI changes apply.

CI

GitHub Actions runs lint + tests + build on every PR.

---

Staged PR plan

PR1 (README): update README with scope, setup, run, config, troubleshooting, security, and contribution workflow.

PR2 (Reliability):

• remove duplicate/dead classes
• centralize config validation
• structured logging + error handling
• add lint/type checks + CI updates
• add tests for config validation + CLI help paths

PR3 (UX/DX):

• improve CLI error messages
• add --help and readable usage output
• better batch empty-state handling

Patch suggestions (high-level)

• Remove duplicate root-level src/Pipeline.php + related legacy classes; keep src/Core/* versions.
• Introduce src/Core/Config.php to validate config + env overrides.
• Fix src/Cli/ArgvParser.php to support --help and consistent option parsing.
• Update .github/workflows/ci.yml to run lint, phpstan, and tests.