Download the PHP package dedsecteam17/soft-mapper without Composer

Soft-Mapper

A lightweight, powerful, and easy-to-use PHP ORM (Object-Relational Mapping) library for MySQL databases. Soft-Mapper provides a clean and intuitive interface for database operations with built-in security features and advanced ORM capabilities.

🚀 What's New in v2.0

Version 2.0 brings 27 new methods and advanced ORM features that make Soft-Mapper comparable to Laravel's Eloquent:

• ✨ Automatic Timestamps - Auto-manage created_at/updated_at
• ✨ Soft Deletes - Mark records as deleted without removing them
• ✨ ORM Relationships - Define 1:1, 1:N, and N:N relationships (NEW!)
• ✨ Eager Loading - Load relationships efficiently to prevent N+1 queries (NEW!)
• ✨ Query Scopes - Reusable query constraints
• ✨ Batch Operations - Insert multiple records efficiently
• ✨ Transactions - Full transaction support
• ✨ Advanced Queries - whereIn, whereBetween, whereNull, JOINs
• ✨ Helper Methods - count(), exists(), first(), pluck()
• ✨ And much more! - See CHANGELOG.md for complete list

📚 Documentation:

• Quick Start Guide - Get started with new features
• ORM Relationships Guide - Complete guide to relationships (NEW!)
• Changelog - Complete list of changes
• Advanced Examples - Real-world usage examples

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Usage
  • Creating Models
  • Basic CRUD Operations
  • Advanced Queries
  • Aggregate Functions
• Advanced Features
• API Reference
• Examples
• Security
• Troubleshooting
• Contributing
• License
• Author

Features

Core Features

• ✅ Simple and Intuitive API: Easy-to-understand method chaining interface
• ✅ Full CRUD Support: Create, Read, Update, and Delete operations
• ✅ Query Builder: Build complex SQL queries with simple PHP methods
• ✅ Security First: Built-in prepared statements prevent SQL injection
• ✅ Aggregate Functions: Support for COUNT, SUM, AVG, MIN, MAX, etc.
• ✅ Flexible Filtering: WHERE and HAVING clauses with multiple conditions
• ✅ Result Ordering: ORDER BY with ASC/DESC support
• ✅ Result Grouping: GROUP BY for aggregate queries
• ✅ Result Limiting: LIMIT clause for pagination
• ✅ Method Chaining: Chain multiple methods for complex queries
• ✅ PDO-Based: Uses PHP Data Objects for database abstraction
• ✅ Lightweight: Minimal dependencies, single-file implementation

Advanced Features ⭐ NEW

• ✨ Automatic Timestamps: Auto-manage created_at and updated_at columns
• ✨ Soft Deletes: Mark records as deleted without removing from database
• ✨ ORM Relationships: Define and query 1:1, 1:N, and N:N relationships
• ✨ Eager Loading: Load relationships efficiently with with()
• ✨ Relationship Methods: hasOne(), hasMany(), belongsTo(), belongsToMany()
• ✨ Pivot Table Operations: attach(), detach(), sync() for many-to-many
• ✨ Pagination with OFFSET: Full pagination support with limit and offset
• ✨ Custom Primary Keys: Support for non-'id' primary key columns
• ✨ Batch Operations: Insert multiple records efficiently with insertMany()
• ✨ Query Scopes: Define reusable query constraints
• ✨ JOIN Support: INNER JOIN, LEFT JOIN, RIGHT JOIN operations
• ✨ Advanced WHERE Clauses: whereIn, whereNotIn, whereBetween, whereNull
• ✨ Helper Methods: first(), count(), exists(), pluck()
• ✨ Transaction Support: Complete transaction management
• ✨ Raw Queries: Execute custom SQL when needed
• ✨ Chunking: Memory-efficient processing of large datasets
• ✨ Update or Create: Intelligent upsert operations
• ✨ Distinct Results: Get unique records only

Requirements

• PHP: Version 5.6 or higher (PHP 7.x or 8.x recommended)
• MySQL: Version 5.5 or higher
• PHP Extensions:
  • PDO
  • PDO_MySQL

Installation

Using Composer (Recommended)

Install via Composer:

Then include the autoloader in your project:

Manual Installation

1. Clone this repository or download the files:

2. Include the library in your project:

Using as a Git Submodule

Then include in your code:

Quick Start

Configuration

Database Configuration

Edit env.php to configure your database connection:

Environment-Specific Configuration

For production environments, consider using environment variables:

Usage

Creating Models

Each model represents a database table. Extend the SoftMapper class:

Basic CRUD Operations

Create (Insert)

Insert new records into the database:

Read (Select)

Find by ID:

Get All Records:

Get Single Record:

Select Specific Columns:

Update

Update existing records:

Update Multiple Records:

Delete

Delete records from the database:

Delete Multiple Records:

Advanced Queries

WHERE Clauses

Simple WHERE:

Multiple Conditions with AND:

Using Different Operators:

ORDER BY

Order Descending:

Order Ascending:

LIMIT

Limit Results:

Pagination Example:

Combining Multiple Clauses

Aggregate Functions

COUNT

Count all records:

Count with GROUP BY:

SUM, AVG, MIN, MAX

HAVING Clause

Use HAVING with aggregate functions:

Advanced Features

Automatic Timestamps

Enable automatic timestamp management for created_at and updated_at columns:

Soft Deletes

Soft delete marks records as deleted without removing them from the database:

Custom Primary Keys

Override the default 'id' primary key:

Pagination with OFFSET

Full pagination support:

Batch Insert

Insert multiple records efficiently:

Advanced WHERE Clauses

WHERE IN

WHERE NOT IN

WHERE BETWEEN

WHERE NULL / WHERE NOT NULL

Query Scopes

Define reusable query constraints:

JOIN Operations

Perform table joins:

Helper Methods

first()

Get the first record:

count()

Count records:

exists()

Check if records exist:

pluck()

Get a single column's values:

Transaction Support

Manage database transactions:

Raw Queries

Execute custom SQL:

Chunking

Process large datasets efficiently:

Update or Create

Update existing record or create new one:

Distinct Results

Get unique records:

Get Last Insert ID

ORM Relationships

Soft-Mapper now supports defining and querying relationships between models, making it easy to work with related data.

Defining Relationships

Define relationships in your model classes:

Loading Relationships

Lazy Loading (load relationships as needed):

Eager Loading (load relationships efficiently for multiple records):

Many-to-Many Operations

Manage many-to-many relationships with pivot table operations:

Complete Example

📚 For complete relationship documentation, see RELATIONSHIPS.md

API Reference

Core Methods

Advanced Methods

Relationship Methods

Condition Array Format

For where() and having() methods:

Supported Operators: =, >, <, >=, <=, !=, <>

Logical Operators: AND, OR

Examples

See the example.php file for complete working examples. Here are some real-world scenarios:

Blog Post Management

User Management

Security

SQL Injection Protection

Soft-Mapper uses PDO prepared statements for all database queries, which automatically protects against SQL injection attacks. User input is never directly concatenated into SQL queries.

Best Practices

1. Never expose database credentials: Keep env.php outside your web root or use environment variables
2. Validate user input: Even though SQL injection is prevented, validate data types and formats
3. Hash passwords: Always use password_hash() for storing passwords
4. Sanitize output: Use htmlspecialchars() when displaying data in HTML
5. Use HTTPS: Encrypt data in transit
6. Implement access controls: Check user permissions before database operations

Example with validation:

Troubleshooting

Common Issues

1. PDO Connection Error

Solution: Check your database configuration in env.php. Ensure MySQL is running.

2. Table doesn't exist

Solution: Verify that $table_name in your model matches your actual database table name.

3. Column not found

Solution: Ensure column names in $columns array match your database schema.

4. Class 'PDO' not found

Solution: Enable the PDO and PDO_MySQL extensions in your php.ini:

Debug Mode

To see the generated SQL queries, you can temporarily add debugging to the SoftMapper class:

Getting Help

If you encounter issues:

1. Check the examples section
2. Review your database configuration
3. Verify your table and column names
4. Check PHP and MySQL versions meet requirements
5. Open an issue on GitHub

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes: Implement your feature or bug fix
4. Test your changes: Ensure everything works as expected
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Follow PSR coding standards
• Add comments for complex logic
• Update documentation for new features
• Test with multiple PHP versions if possible
• Keep backward compatibility in mind

License

This project is open source and available under the MIT License. Feel free to use, modify, and distribute this software.

Author

Mohammed Elamin

• Created: December 2018
• GitHub: @DedSecTeam17

Star this Repository ⭐

If you find Soft-Mapper useful, please consider giving it a star on GitHub. It helps others discover the project!

Support

For questions, issues, or feature requests, please visit:

• GitHub Issues
• GitHub Discussions

Happy Coding! 🚀