Download the PHP package codewithkyrian/huggingface without Composer

Hugging Face PHP

A comprehensive PHP client for the Hugging Face Hub. Access thousands of machine learning models, datasets, run inference, and more, all from your PHP application.

• Hub API: Full CRUD support for Repositories (Models, Datasets, Spaces), Files, and Collections.
• Inference API: Run inference on over 100,000+ models using Hugging Face's serverless abstraction. Automatically resolves the best provider for you.
• Smart Caching: Built-in, OS-aware caching system with support for generic file caching and optimization.
• Type-Safe: Fully typed DTOs for strict typing and better developer experience.
• Utilities: Includes specific utilities for various tasks like token classification, zero-shot classification, and more.

Table of Contents

• Installation
• Quick Start
• Configuration
• Hub API
  • Repository Basics
  • Repository Info
  • Creating Repositories
  • Updating Repositories
  • Repository Operations
  • Branch Management
  • File Operations
  • Downloading Files
  • Downloading Entire Repositories
  • Uploading Files
  • Deleting Files
  • Listing Commits
  • Collections
  • Searching Models, Datasets, and Spaces
• Inference API
  • Provider Configuration
  • Chat Completion
  • Text Generation
  • Feature Extraction (Embeddings)
  • Text Classification
  • Token Classification
  • Summarization
  • Question Answering
  • Translation
  • Fill Mask
  • Sentence Similarity
  • Text to Image
  • Image Classification
  • Object Detection
  • Image to Text
  • Text to Speech
  • Automatic Speech Recognition
• Caching
• Error Handling
• Examples
• API Reference

Installation

Install the package via Composer:

Requirements

• PHP 8.2 or higher
• A PSR-18 HTTP client (e.g., Guzzle, Symfony HttpClient)

If you don't have a PSR-18 client installed, add Guzzle:

Quick Start

The client works without authentication for public resources:

For operations requiring authentication (private repos, inference, uploads), provide a token:

Configuration

Authentication

A token is optional for public Hub operations (downloading, searching, listing). You need a token for:

• Accessing private repositories
• Running inference on most models
• Uploading files or creating repositories

Getting a token:

1. Create a free account at huggingface.co
2. Go to Settings → Access Tokens
3. Create a token with appropriate permissions

Basic Setup

Environment Variables

The client automatically checks these environment variables:

Advanced Configuration

Use the factory for full control:

Hub API

The Hub API lets you manage repositories, upload models, and search the Hugging Face Hub.

Repository Basics

Get a RepoManager for any repository. All operations (info, files, download, commit) flow through it.

Working with Revisions

By default, operations use the main branch. Use revision() to target a specific branch, tag, or commit.

Repository Info

Get metadata about a repository.

Shorthand methods when you only need metadata:

Creating Repositories

Create Options

Updating Repositories

Repository Operations

Branch Management

Deleting Repositories

File Operations

Listing Files

Listing Options

File Information

Downloading Files

Download Options

Cache Helpers

Downloading Entire Repositories

Download all files to a local cached snapshot.

Snapshots are additive, so you can call snapshot() multiple times to build up a local content cache. Use force: false to skip the remote update check if you already have a cached revision.

Uploading Files

Quick Upload

Commit Builder

For complex operations, use the commit builder:

addFile() accepts: string (content or path), URL, or resource (stream).

Deleting Files

Listing Commits

[!NOTE] commits() returns a Generator that fetches pages lazily. The batchSize argument (1–1000) controls how many commits are fetched per API request; the generator keeps requesting more pages until all commits are returned, so use a break when you have enough results.

Collections

Collections are curated lists of models, datasets, spaces, or papers.

Listing Collections

Creating Collections

Managing Items

Searching Models, Datasets, and Spaces

Search returns a Generator that fetches results lazily.

Models

Model Search Options

Datasets

Spaces

[!WARNING] Without limit(), the generator fetches ALL matching results. Always set a limit or break manually.

Inference API

The Inference API lets you run machine learning models on Hugging Face's infrastructure. It supports text generation, embeddings, classification, image generation, speech recognition, and more.

Provider Configuration

The inference client supports multiple providers. Pass the provider directly to inference():

Supported Providers

Provider Resolution

When you don't specify a provider (or use InferenceProvider::Auto), the client automatically selects the best available provider for your model. Here's how it works:

1. Map Model Providers: The client queries the Hugging Face Hub to find all providers that serve this model following the priority order of providers you've configured in your Inference Provider settings on Hugging Face.
2. Availability & Compatibility: It selects the first provider that is currently available and supports the requested task.
3. Exception: If no viable provider is found for the model and task, a RoutingException is thrown.

This ensures you always get the most reliable inference endpoint based on your personal or organization settings.

Billing

Bill requests to an organization:

Chat Completion

Chat with large language models using a conversational interface. Supports system prompts, multi-turn conversations, and streaming.

Multi-turn Conversations

Streaming

Options

Text Generation

Generate text continuations from a prompt. Unlike chat completion, this is for raw text completion without conversation structure.

Options

Also supports: adapterId, details, grammar, topNTokens, typicalP

Feature Extraction (Embeddings)

Generate vector embeddings for text. Useful for semantic search, clustering, and similarity comparisons.

Options

Text Classification

Classify text into categories. Returns scored labels.

Options

Token Classification

Classify individual tokens in a text, such as identifying entities (NER) or parts of speech (POS).

Options

Summarization

Summarize long text into shorter versions.

Options

Question Answering

Extract answers from a context passage.

Options

Translation

Translate text between languages. Model determines the language pair.

Options

Supports other generation parameters like topK, topP, etc.

Fill Mask

Predict masked tokens in text (like BERT's pre-training task).

Options

Sentence Similarity

Compare a source sentence against multiple target sentences.

Text to Image

Generate images from text prompts.

Options

Image Classification

Classify images into categories.

Options

Object Detection

Detect objects in an image with bounding boxes.

Options

Image to Text

Generate captions for images.

Options

Supports other standard generation parameters: earlyStopping, numBeamGroups, penaltyAlpha, useCache, etaCutoff, epsilonCutoff, typicalP

Text to Speech

Convert text to audio.

Options

Supports other standard generation parameters: earlyStopping, numBeamGroups, penaltyAlpha, useCache, etaCutoff, epsilonCutoff, typicalP

Automatic Speech Recognition

Transcribe audio to text.

Zero-Shot Classification

Classify text into arbitrary categories without training.

Options

Caching

The library uses a unified repository-based cache system with blob deduplication. This means:

• Files are stored once by their content hash (blob storage)
• Multiple snapshots share the same blob files via symlinks
• Files are only re-downloaded when they change on the server
• Repeated downloads are instant
• Zero-latency file checks using local manifests
• Your internet connection isn't required for cached files

Cache Structure

Cache Management

You can inspect and manage the cache programmatically:

Default Cache Location

The cache is stored in a platform-appropriate location:

• Linux: ~/.cache/huggingface/hub or $XDG_CACHE_HOME/huggingface/hub
• macOS: ~/Library/Caches/huggingface/hub
• Windows: %LOCALAPPDATA%\huggingface\hub

You can override with the HF_HUB_CACHE or HF_HOME environment variables.

Custom Cache Directory

Downloading to Cache

Disabling Cache

Force Re-download

Error Handling

The library uses specific exception types for different error conditions:

Automatic Retries

The library automatically retries on transient failures:

• Server errors (5xx): Retried with exponential backoff
• Rate limits (429): Retried after the Retry-After delay
• Network failures: Retried up to 3 times

This happens transparently so you don't need to implement retry logic yourself.

Examples

The examples/ directory contains ready-to-run scripts:

Run any example:

API Reference

See the API Reference for complete documentation of all classes and methods.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.