خرج الصورة

يمكن إنشاء صورة باستخدام دوال image*‎ حيث * هي صيغة الملف، وهذه الدوال لها الصيغة المشتركة التالية:

bool image___(resource $im [, mixed $to [ other parameters]] )

الحفظ إلى ملف

يمكنك تمرير اسم الملف أو مجرى ملف مفتوح للمتغير ‎$to إذا كنت تريد حفظ الصورة إلى ملف، إذا مررت مجرى فلا تحتاج لإغلاقه لأنّ مكتبة GD تغلقه تلقائيًا، مثلًا لحفظ ملف PNG:

imagepng($image, "/path/to/target/file.png"); 

$stream = fopen("phar://path/to/target.phar/file.png", "wb"); 
imagepng($image2, $stream);
// لا حاجة لإغلاق المجرى

تأكد عند استخدام fopen من أنك تستخدم الراية b وليس الراية t لأن الملف هو خرج ثنائي، ولا تحاول أن تمرر fopen("php://temp", $f)‎ أو fopen("php://memory", $f)‎ لأنّ الدالة تُغلق المجرى بعد الاستدعاء ولن تبقى قادرًا على استدعائه أو استخدامه لاسترداد محتوياته مثلًا.

الخرج كرد HTTP

لا تحتاج إلى تمرير شيء (أو مرر null) كوسيط ثانٍ إذا كنت تريد أن ترجع هذه الصورة مباشرةً كرد للصورة (لإنشاء بطاقات ديناميكية مثلًا)، لكنك تحتاج إلى تحديد نوع المحتوى في رد HTTP:

header("Content-Type: $mimeType");

‎$mimeType هو نوع الصياغة المُرجعة في الترويسة MIME مثل image/png وimage/gif وimage/jpeg.

الكتابة إلى متغير

يوجد طريقتين للكتابة إلى متغير:

• استخدام المخزن المؤقت للخرج (OB):

ob_start(); 
// ‫تمرير null للكتابة افتراضيًا في مجرى الخرج القياسي
imagepng($image, null, $quality); 
$binary = ob_get_clean();

• استخدام مغلِّف المجرى:

قد يكون لديك سبب ما لعدم استخدام المخزن المؤقت للخرج كأن يكون لديك بالفعل مخزن مؤقت قيد التشغيل لذا تحتاج إلى بديل، يمكنك تسجيل مغلَّف مجرى جديد باستخدام الدالة stream_wrapper_register لذا يمكنك تمرير مجرى إلى دالة إظهار الصورة واستعادته لاحقًا.

<?php
class GlobalStream{
    private $var;

    public function stream_open(string $path){
        this->var =& $GLOBALS[parse_url($path)["host"]];
        return true;
    }

    public function stream_write(string $data){
        $this->var .= $data;
        return strlen($data);
    }
}

stream_wrapper_register("global", GlobalStream::class);

$image = imagecreatetruecolor(100, 100);
imagefill($image, 0, 0, imagecolorallocate($image, 0, 0, 0));

$stream = fopen("global://myImage", "");
imagepng($image, $stream);
echo base64_encode($myImage);

في هذا المثال يكتب الصنف GlobalStream أي دخل إلى المتغير المرجعي (أي الكتابة بشكل غير مباشر إلى المتغير العام للاسم المعطى)، يمكن استرجاع المتغير العام لاحقًا بشكلٍ مباشر.

يجب الانتباه إلى عدة أمور:

• صنف مغلِّف المجرى المنفَّذ بشكلٍ كامل يجب أن يشبه هذا الصنف لكن وفقًا للاختبارات باستخدام تابع ‎__call السحري فإنّه من الممكن استدعاء stream_open وstream_write وstream_close فقط من الدوال الداخلية.
• لا توجد رايات مطلوبة في استدعاء fopen لكن يجب أن تمرر سلسلة فارغة على الأقل، لأنّ الدالة fopen تتوقع مثل هذا المعامل، حتى لو لم تستخدمها في تنفيذ stream_open يبقى هذا المعامل مطلوبًا.
• تستدعى الدالة stream_write عدة مرات وفقًا للاختبارات، تذكر أن تستخدم إسناد الدمج ‎.=‎ وليس إسناد المتغير المباشر =.

مثال: في وسم <img> في HTML، يمكن توفير صورة بشكلٍ مباشر بدلًا من استخدام رابط خارجي:

echo '<img src="data:image/png;base64,' . base64_encode($binary) . '">';

إنشاء صورة

نستخدم الدالة imagecreatetruecolor لإنشاء صورة فارغة:

$img = imagecreatetruecolor($width, $height);

المتغير ‎$img‎ هو متغير مورد الآن بعرض ‎$width وطول ‎$height بكسل، لاحظ أنّ العرض يُحسب من اليسار إلى اليمين والطول من الأعلى إلى الأسفل.

يمكن أن يُنشأ أيضًا مورد الصورة من دوال إنشاء الصورة مثل imagecreatefrompng وimagecreatefromjpeg ودوال imagecreatefrom*‎ أخرى.

قد تُحرَّر موارد الصورة لاحقًا عندما لا توجد مراجع إليها، لكن لتحرير الذاكرة بشكلٍ مباشر (قد يكون هذا مهمًا عند معالجة عدة صور كبيرة) يمكننا استخدام imagedestroy()‎ على الصورة عندما لا تبقى حاجة لاستخدامها وتكون هذه ممارسة جيدة.

imagedestroy($image);

تحويل صورة

إنّ الصور التي تُنشأ من تحويل الصور لا تعدّل الصورة حتى تُخرجها، لذا يمكن أن يكون محوِّل الصورة ببساطة عبارة عن ثلاثة أسطر من الشيفرة:

function convertJpegToPng(string $filename, string $outputFile) {
    $im = imagecreatefromjpeg($filename);
    imagepng($im, $outputFile);
    imagedestroy($im);
}

اقتصاص الصورة وتغيير حجمها

يمكنك استخدام الدالة imagecopyresampled إذا كان لديك صورة وتريد إنشاء صورة جديدة بأبعاد جديدة، أنشئ أولًا صورة جديدة بالأبعاد المرغوبة:

// صورة جديدة
$dst_img = imagecreatetruecolor($width, $height);

خزّن الصورة الأصلية في متغير، يمكنك القيام بذلك باستخدام إحدى دوال createimagefrom*‎ حيث يمكن أن تكون * هي jpeg أو gif أوpng أوstring، مثال:

// الصورة الأصلية
$src_img=imagecreatefromstring(file_get_contents($original_image_path));

ثم استخدم الدالة imagecopyresampled لنسخ كل الصورة الأصلية (أو جزء منها) (src_img) إلى الصورة الجديدة (dst_img):

imagecopyresampled($dst_img, $src_img,
    $dst_x ,$dst_y, $src_x, $src_y,
    $dst_width, $dst_height, $src_width, $src_height);

لضبط أبعاد src_*‎ و‎dst_*‎، استخدم الصورة التالية:

إذا كنت تريد الآن نسخ كامل الصورة المصدر (الأصلية) إلى كامل منطقة الهدف (بدون اقتصاص):

$src_x = $src_y = $dst_x = $dst_y = 0;

// عرض الصورة الجديدة
$dst_width = $width;

// طول الصورة الجديدة
$dst_height = $height;

// عرض الصورة الأصلية
$src_width = imagesx($src_img);

// طول الصورة الأصلية
$src_height = imagesy($src_img);

مكتبة Imagick

التثبيت

• باستخدام apt في الأنظمة المعتمدة على Debian:

sudo apt-get install php5-imagick

• باستخدام Homebrew في أنظمة OSX/macOs:

brew install imagemagick

• باستخدام الإصدارات الثنائية: التعليمات في موقع imagemagick.

الاستخدام

<?php
$imagen = new Imagick('imagen.jpg');
// ‫إذا وضعت قيمة المعامل 0 ستتم المحافظة على نسبة العرض
$imagen->thumbnailImage(100, 0);

echo $imagen;
?>

تحويل صورة إلى سلسلة نصية بالأساس 64

يُظهر هذا المثال كيفية تحويل صورة إلى سلسلة نصية بالأساس 64 (أي سلسلة نصية يمكنك استخدامها مباشرةً في السمة src لوسم img)، يستخدم هذا المثال مكتبة Imagick لكن يمكن استخدام مكتبات أخرى مثل GD.

<?php
// (1)
$img = new Imagick('image.jpg');

// (2)
$img->resizeImage(320, 240);

// (3)
$imgBuff = $img->getimageblob();

// (4)
$img->clear();

// (5)
$img = base64_encode($imgBuff);
echo "<img alt='Embedded Image' src='data:image/jpeg;base64,$img' />";

في الموضع (1) يُحمَّل الملف image.jpg للمعالجة، مسار الملف نسبي إلى ملف ‎.php‎ المتضمن هذه الشيفرة لذا في هذا المثال يجب أن يكون ملف image.jpg في نفس مجلد السكربت.

في الموضع (2) يتغير حجم الصورة للحجم المُعطى كطول وعرض وإذا أردت تغيير دقة الصورة أيضًا مع تغيير الحجم يمكنك استخدام الدالة ‎$img->resampleimage(320, 240)‎، لاحظ أنّه يمكنك ضبط المعامل الثاني إلى 0 للمحافظة على نسبة عرض الصورة.

في الموضع (3) تُرجع الدالة تمثيل الصورة على شكل سلسلة نصية غير مشفرة.

في الموضع (4) يُزال المورد image.jpg من الكائن ‎$img‎ ويُدمَّر الكائن مما يحرر موارد النظام المحجوزة لمعالجة الصورة.

في الموضع (5) تُنشأ نسخة بتشفير الأساس 64 من السلسلة النصية السابقة غير المشفرة ثم تُعرَض كصورة في الصفحة، لاحظ أنّه قد يتغير الجزء image/jpeg في السمة src وذلك بالاعتماد على نوع الصورة التي تستخدمها (png أوjpeg مثلًا).

ترجمة -وبتصرف- للفصول [Image Processing with GD - Imagick] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: مدخل إلى تعلم الآلة (Machine learning) في PHP
• المقال السابق: اصطلاحات ومواضيع متفرقة مهمة لكل مبرمج PHP

وسوم PHP

يجب أن تستخدم دائمًا الوسوم ‎<?php ?>‎ أو وسوم الطباعة القصيرة ‎<?= ?>‎، ويجب ألا تُستخدم الاختلافات الأخرى (خاصةً الوسوم القصيرة <? ?>) لأنّ مديري النظام يعطلونها عادةً.

يجب تجاهل صيغة الإغلاق ‎?>‎ عندما لا نتوقع أن ينتج الملف خرجًا لتجنب الخرج غير المقصود الذي يمكن أن يسبب مشاكل عندما يحلل العميل الملف خاصةً أنّ بعض المتصفحات تفشل في التعرف على وسم ‎<!DOCTYPE وتنشّط نمط التجاوزات Quirks Mode.

مثال عن سكربت PHP بسيط:

<?php
print "Hello World";

مثال عن ملف تعريف صنف:

<?php
class Foo
{
    ...
}

مثال عن PHP مضمن في HTML:

<ul id="nav">
    <?php foreach ($navItems as $navItem): ?>
        <li><a href="<?= htmlspecialchars($navItem->url) ?>">
            <?= htmlspecialchars($navItem->label) ?>
        </a></li>
    <?php endforeach; ?>
</ul>

فوائد المولّدات (Generators)

تقدّم PHP 5.5 المولّدات والكلمة المفتاحية yield التي تسمح لنا بكتابة شيفرة غير متزامنة تبدو أشبه بالشيفرة المتزامنة، يعدّ التعبير yield مسؤولًا عن إعادة التحكم إلى الشيفرة المستدعاة وتوفير نقطة استئناف من هناك، يمكنك إرسال قيمة مع تعليمة yield، القيمة المرجعة من هذا التعبير إما null أو القيمة الممررة إلى Generator::send()‎.

function reverse_range($i) {
    // ‫مجرد وجود الكلمة المفتاحية `yield` في هذه الدالة يجعلها مولّد
    do {
        // ‎$i‎ هي القيمة المُحتفظ بها بين الاستئنافات
        print yield $i;
    } while (--$i > 0);
}

$gen = reverse_range(5);
print $gen->current();

// الإرسال أيضًا يستأنف المولِّد
$gen->send("injected!");

foreach ($gen as $val) {
    // المرور على كامل محتويات المولّد مما يجعله يستأنف عند كل تكرار
    echo $val;
}

// 5injected!4321

يمكن استخدام هذه الآلية بتنفيذ نمط مشترك (coroutine) لانتظار كائنات Awaitable المُعادة من المولِّد (بتسجيل المولّد نفسه كرد نداء للحل) ومواصلة تنفيذ المولّد بمجرد إنهاء كائن Awaitable.

استخدام حلقة حدث من مكتبة Icicle

تستخدم مكتبة Icicle كائنات Awaitable ومولّدات لإنشاء نمط مشترك.

require __DIR__ . '/vendor/autoload.php';

use Icicle\Awaitable;
use Icicle\Coroutine\Coroutine;
use Icicle\Loop;

$generator = function (float $time) {
    try {
        // ‫ضبط المتغير ‎$start إلى القيمة المعادة من الدالة microtime()‎? بعد ‎$time ثانية تقريبًا
        $start = yield Awaitable\resolve(microtime(true))->delay($time);
        echo "Sleep time: ", microtime(true) - $start, "\n";

        // ‫رمي استثناء من كائن Awaitable المرفوض إلى النمط المشترك
        return yield Awaitable\reject(new Exception('Rejected awaitable'));
    } catch (Throwable $e) {
        // ‫التقاط سبب رفض awaitable
        echo "Caught exception: ", $e->getMessage(), "\n";
    }
    return yield Awaitable\resolve('Coroutine completed');
};

// يبقى النمط المشترك ساكنًا لمدة 1.2 ثانية ثم ينتهي معيدًا سلسلة نصية
$coroutine = new Coroutine($generator(1.2));
$coroutine->done(function (string $data) {
    echo $data, "\n";
});

Loop\run();

إنتاج عمليات غير معطَّلة مع proc_open()‎

لا تدعم PHP تنفيذ الشيفرة بشكلٍ متزامن إلا إذا ثبَّت الإضافات مثل pthread، يمكن تجاوز هذا أحيانًا باستخدام الدوال proc_open()‎ وstream_set_blocking()‎­ وقراءة خرجهم بشكلٍ غير متزامن.

يمكننا تنفيذ الشيفرة كعمليات فرعية متعددة إذا قسمناها إلى أجزاء أصغر، ثمّ يمكننا جعل كل عملية فرعية غير معطَّلة باستخدام دالة stream_set_blocking()‎ أي أنّه يمكننا إنتاج عدة عمليات فرعية ثم التحقق من خرجها في حلقة (بشكل مشابه لحلقة حدث) والانتظار حتى تنتهي جميعها.

يمكن أن يكون لدينا مثلًا عملية فرعية صغيرة تنفّذ حلقة وتتوقف في كل تكرار بشكلٍ عشوائي لمدة 100- 1000 ميلي ثانية (لاحظ أنّ التأخير هو نفسه لكل عملية فرعية).

<?php
// subprocess.php
$name = $argv[1];
$delay = rand(1, 10) * 100;
printf("$name delay: ${delay}ms\n");

for ($i = 0; $i < 5; $i++) {
    usleep($delay * 1000);
    printf("$name: $i\n");
}

ثم ستنتج العملية الرئيسية عمليات فرعية وتقرأ خرجها، ويمكننا تقسيمه إلى كتل أصغر:

• إنتاج عمليات فرعية باستخدام proc_open()‎.
• جعل كل عملية فرعية غير معطَّلة باستخدام stream_set_blocking()‎.
• تنفيذ حلقة حتى تنتهي كل العمليات الفرعية باستخدام proc_get_status()‎.
• إغلاق مقابض الملف بشكل صحيح مع أنبوب الخرج لكل عملية فرعية باستخدام fclose()‎ وإغلاق مقابض العملية باستخدام proc_close()‎.

<?php
// non-blocking-proc_open.php
// واصفات الملف لكل عملية فرعية
$descriptors = [
    ᠎᠎0 => ['pipe', 'r'], // stdin
    1 => ['pipe', 'w'], // stdout
];

$pipes = [];
$processes = [];
foreach (range(1, 3) as $i) {
    // إنتاج عملية فرعية
    $proc = proc_open('php subprocess.php proc' . $i, $descriptors, $procPipes);
    $processes[$i] = $proc;
    // جعل العملية الفرعية غير معطَّلة (أنبوب الخرج فقط)
    stream_set_blocking($procPipes[1], 0);
    $pipes[$i] = $procPipes;
}

// تنفيذ حلقة حتى تنتهي كل العمليات الفرعية
while (array_filter($processes, function($proc) { return proc_get_status($proc)['running']; })) {
    foreach (range(1, 3) as $i) {
        usleep(10 * 1000); // 100ms
        // ‫قراءة كل الخرج الممكن (الخرج غير المقروء يُخزَّن مؤقتًا)
        $str = fread($pipes[$i][1], 1024);
        if ($str) {
            printf($str);
        }
    }
}

// إغلاق كل الأنابيب والعمليات
foreach (range(1, 3) as $i) {
    fclose($pipes[$i][1]);
    proc_close($processes[$i]);
}

يحتوي الخرج على مزيج من العمليات الفرعية الثلاث بما أننا نقرأها باستخدام fread()‎، لاحظ أنّه في المثال انتهت العملية proc1 قبل العمليتين الباقيتين بكثير.

$ php non-blocking-proc_open.php
proc1 delay: 200ms
proc2 delay: 1000ms
proc3 delay: 800ms
proc1: 0
proc1: 1
proc1: 2
proc1: 3
proc3: 0
proc1: 4
proc2: 0
proc3: 1
proc2: 1
proc3: 2
proc2: 2
proc3: 3
proc2: 3
proc3: 4
proc2: 4

قراءة منفذ تسلسلي مع إضافة حدث ودخل/خرج مباشر

إنّ مجاري الدخل والخرج المباشرة (DIO) غير معروفة الآن من قِبل الإضافة حدث Event، فلا توجد طريقة نظيفة للحصول على واصف الملف مغلفًا ضمن موارد الدخل والخرج المباشرة، إلا أنّ هناك حل بديل:

• فتح مجرى للمنفذ باستخدام fopen()‎.
• جعل المجرى غير معطّل باستخدام stream_set_blocking();‎.
• الحصول على واصف ملف رقمي من المجرى باستخدام EventUtil::getSocketFd();‎.
• تمرير واصف الملف الرقمي إلى الدالة dio_fdopen()‎ والحصول على مورد دخل/خرج مباشر.
• إضافة حدث مع رد نداء للتنصت على الأحداث المقروءة على واصف الملف.
• تُصرَف البيانات المتاحة في رد النداء وتُعالج وفقًا لمنطق تطبيقك.

الملف dio.php:

<?php
class Scanner {
    // ‫مسار المنفذ مثل  ‎/dev/pts/5
    protected $port;
    // واصف الملف الرقمي
    protected $fd;
    // EventBase
    protected $base;
    // مورد دخل/خرج مباشر 
    protected $dio;
    // حدث
    protected $e_open; 
    // حدث
    protected $e_read;

    public function __construct ($port) {
        $this->port = $port;
        $this->base = new EventBase();
    }

    public function __destruct() {
        $this->base->exit();
        if ($this->e_open)
            $this->e_open->free();
        if ($this->e_read)
            $this->e_read->free();
        if ($this->dio)
            dio_close($this->dio);
    }

    public function run() {
        $stream = fopen($this->port, 'rb');
        stream_set_blocking($stream, false);
        $this->fd = EventUtil::getSocketFd($stream);
        if ($this->fd < 0) {
            fprintf(STDERR, "Failed attach to port, events: %d\n", $events);
            return;
        }
        $this->e_open = new Event($this->base, $this->fd, Event::WRITE, [$this, '_onOpen']);
        $this->e_open->add();
        $this->base->dispatch();
        fclose($stream);
    }

    public function _onOpen($fd, $events) {
        $this->e_open->del();
        $this->dio = dio_fdopen($this->fd);

        // استدعاء دوال دخل/خرج مباشر هنا
        dio_tcsetattr($this->dio, [
            'baud' => 9600,
            'bits' => 8,
            'stop' => 1,
            'parity' => 0
        ]);

        $this->e_read = new Event($this->base, $this->fd, Event::READ | Event::PERSIST,
        [$this, '_onRead']);
        $this->e_read->add();
    }

    public function _onRead($fd, $events) {
        while ($data = dio_read($this->dio, 1)) {
            var_dump($data);
        }
        }
    }

// تغيير وسيط المنفذ
$scanner = new Scanner('/dev/pts/5');
$scanner->run();

الاختبار: نفّذ التعليمة التالية في الطرفية A:

$ socat -d -d pty,raw,echo=0 pty,raw,echo=0
2016/12/01 18:04:06 socat[16750] N PTY is /dev/pts/5
2016/12/01 18:04:06 socat[16750] N PTY is /dev/pts/8
2016/12/01 18:04:06 socat[16750] N starting data transfer loop with FDs [5,5] and [7,7]

قد يختلف الخرج، استخدم الطرفيات الزائفة من أول سطرين (‎/dev/pts/5‎ و‎/dev/pts/8 بالتحديد).

نفّذ في الطرفية B السكربت السابق، قد تحتاج إلى صلاحيات الجذر:

$ sudo php dio.php

أرسل من الطرفية C سلسلة نصية إلى الطرفية الزائفة الأولى:

$ echo test > /dev/pts/8

الخرج:

string(1) "t"
string(1) "e"
string(1) "s"
string(1) "t"
string(1) "
"

عميل HTTP بالاعتماد على الإضافة Event

إليك مثال عن صنف عميل HTTP بالاعتماد على الإضافة Event، يسمح هذا الصنف بجدولة عدد من طلبات HTTP ثم تنفيذها بشكلٍ غير متزامن.

ملف http-client.php:

<?php
class MyHttpClient {
    // ‫متغير من الصنف EventBase
    protected $base;
    // مصفوفة كائنات من الصنف EventHttpConnection
    protected $connections = [];

    public function __construct() {
        $this->base = new EventBase();
    }

    // ‫دالة لإرسال كل الطلبات المعلقة (أحداث)، تُرجع void
    public function run() {
        $this->base->dispatch();
    }

    public function __destruct() {
        // ‫تدمير كائنات الاتصال بشكلٍ صريح، لا تنتظر كانس المهملات (GC) وإلا قد يتحرر كائن EventBase باكرًا
        $this->connections = null;
    }

    // (1)
    public function addRequest($address, $port, array $headers,
$cmd = EventHttpRequest::CMD_GET, $resource = '/'){
        $conn = new EventHttpConnection($this->base, null, $address, $port);
        $conn->setTimeout(5);
        $req = new EventHttpRequest([$this, '_requestHandler'], $this->base);
        foreach ($headers as $k => $v) {
            $req->addHeader($k, $v, EventHttpRequest::OUTPUT_HEADER);
        }
        $req->addHeader('Host', $address, EventHttpRequest::OUTPUT_HEADER);
        $req->addHeader('Connection', 'close', EventHttpRequest::OUTPUT_HEADER);
        if ($conn->makeRequest($req, $cmd, $resource)) {
            $this->connections []= $conn;
            return $req;
        }
        return false;
    }

    // (2)
    public function _requestHandler($req, $unused) {
        if (is_null($req)) {
            echo "Timed out\n";
        } else {
            $response_code = $req->getResponseCode();
            if ($response_code == 0) {
                echo "Connection refused\n";
            } elseif ($response_code != 200) {
                echo "Unexpected response: $response_code\n";
            } else {
                echo "Success: $response_code\n";
                $buf = $req->getInputBuffer();
                echo "Body:\n";
                while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
                    echo $s, PHP_EOL;
                }
            }
        }
    }
}

$address = "my-host.local";
$port = 80;
$headers = [ 'User-Agent' => 'My-User-Agent/1.0', ];

$client = new MyHttpClient();

// إضافة طلبات معلقة
for ($i = 0; $i < 10; $i++) {
    $client->addRequest($address, $port, $headers,
EventHttpRequest::CMD_GET, '/test.php?a=' . $i);
}

// إرسال طلبات معلقة
$client->run();

في الموضع (1) نضيف طلب HTTP معلق، معاملاته هي:

• ‎$address: اسم المضيف أو IP، سلسلة نصية.
• ‎$port: رقم المنفذ، عدد صحيح.
• ‎$headers: ترويسات HTTP إضافية، مصفوفة.
• ‎$cmd: ثابت EventHttpRequest::CMD_*‎، عدد صحيح.
• ‎$resource: مورد طلب HTTP مثل '‎/page?a=b&c=d'، سلسلة نصية. القيمة المعادة إما EventHttpRequest أو false.

في الموضع (2) نضيف دالة لمعالجة طلب HTTP، معاملاتها:

• ‎$req، كائن من الصنف EventHttpRequest.
• ‎$unused، خليط من المعاملات.

تعيد هذه الدالة void.

الملف test.php، مثال عن سكربت من جهة الخادم:

<?php
echo 'GET: ', var_export($_GET, true), PHP_EOL;
echo 'User-Agent: ', $_SERVER['HTTP_USER_AGENT'] ?? '(none)', PHP_EOL;

الاستخدام:

php http-client.php

مثال عن الخرج:

Success: 200
Body:
GET: array (
    'a' => '1',
)
User-Agent: My-User-Agent/1.0
Success: 200
Body:
GET: array (
    'a' => '0',
)
User-Agent: My-User-Agent/1.0
Success: 200
Body:
GET: array (
    'a' => '3',
)
...
// الخرج مختصر

لاحظ أنّ الشيفرة صُممت للمعالجة طويلة الأمد في CLI SAPI.

عميل HTTP بالاعتماد على الإضافة Ev

إليك مثال عن صنف عميل HTTP بالاعتماد على الإضافة Ev.

تنفذ الإضافة Ev حدث حلقة بسيط لكن قوي للأغراض العامة، إنّها لا توفر مراقبين خاصين للشبكة لكن يمكن استخدام I/O watcher الخاص بالإضافة للمعالجة غير المتزامنة للمقابس.

تظهر الشيفرة التالية كيف يمكن جدولة طلبات HTTP للمعالجة التفرعية.

ملف http-client.php:

<?php
    class MyHttpRequest {
    // ‫كائن من الصنف MyHttpClient
    private $http_client;
    // سلسلة نصية
    private $address;
    // ‫مورد HTTP من النوع سلسلة نصية مثل ‎/page?get=param
    private $resource;
    // ‫طريقة HTTP من النوع سلسلة نصية مثل GET، ‏POST 
    private $method;
    // عدد صحيح
    private $service_port;
    // مقبس مورد
    private $socket;
    // مهلة الاتصال بالثانية من النوع عدد عشري 
    private $timeout = 10.;
    // ‫حجم كل جزء للدالة socket_recv()‎ بالبايتات من النوع عدد صحيح
    private $chunk_size = 20;
    ?// ‫كائن من الصنف EvTimer
    private $timeout_watcher;
    // ‫كائن من الصنف EvIo
    private $write_watcher;
    // ‫كائن من الصنف EvIo
    private $read_watcher;
    // ‫كائن من الصنف EvTimer
    private $conn_watcher;
    // مخزن مؤقت للبيانات القادمة من النوع سلسلة نصية
    private $buffer;
    // الأخطاء التي أخبرت عنها إضافة المقابس في وضع عدم التعطيل من النوع مصفوفة
    private static $e_nonblocking = [
        // ‫عُطِّلت العملية لكن وُضع واصف الملف في وضع عدم التعطيل (EAGAIN أو EWOULDBLOCK)
        11, 
        // ‫العملية الحالية قيد التقدم (EINPROGRESS)
        115,
    ];

    // (1)
    public function __construct(MyHttpClient $client, $host, $resource, $method) {
        $this->http_client = $client;
        $this->host = $host;
        $this->resource = $resource;
        $this->method = $method;

        // ‫الحصول على المنفذ من خدمة WWW
        $this->service_port = getservbyname('www', 'tcp');

        // ‫الحصول على عنوان IP للمضيف الهدف
        $this->address = gethostbyname($this->host);

        // ‫إنشاء مقبس TCP/IP
        $this->socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
        if (!$this->socket) {
            throw new RuntimeException("socket_create() failed: reason: " .
socket_strerror(socket_last_error()));
        }

        // ‫ضبط الراية O_NONBLOCK
        socket_set_nonblock($this->socket);
        $this->conn_watcher = $this->http_client->getLoop()
        ->timer(0, 0., [$this, 'connect']);
    }

    public function __destruct() {
        $this->close();
    }

    private function freeWatcher(&$w) {
        if ($w) {
            $w->stop();
            $w = null;
        }
    }

    // تحرير كل موارد الطلب
    private function close() {
        if ($this->socket) {
            socket_close($this->socket);
            $this->socket = null;
        }
        $this->freeWatcher($this->timeout_watcher);
        $this->freeWatcher($this->read_watcher);
        $this->freeWatcher($this->write_watcher);
        $this->freeWatcher($this->conn_watcher);
    }

    // دالة تهيئ اتصالًا بالمقبس وتعيد قيمة منطقية
    public function connect() {
        $loop = $this->http_client->getLoop();
        $this->timeout_watcher = $loop->timer($this->timeout, 0., [$this, '_onTimeout']);
        $this->write_watcher = $loop->io($this->socket, Ev::WRITE, [$this, '_onWritable']);
        return socket_connect($this->socket, $this->address, $this->service_port);
    }

    // ‫رد نداء لمهلة المراقب (EvTimer)
    public function _onTimeout(EvTimer $w) {
        $w->stop();
        $this->close();
    }

    // رد نداء يُستدعى عندما يصبح المقبس قابلًا للكتابة
    public function _onWritable(EvIo $w) {
        $this->timeout_watcher->stop();
        $w->stop();
        $in = implode("\r\n", [
            "{$this->method} {$this->resource} HTTP/1.1",
            "Host: {$this->host}",
'Connection: Close',
]) . "\r\n\r\n";
        if (!socket_write($this->socket, $in, strlen($in))) {
            trigger_error("Failed writing $in to socket", E_USER_ERROR);
            return;
        }
        $loop = $this->http_client->getLoop();
        $this->read_watcher = $loop->io($this->socket,
Ev::READ, [$this, '_onReadable']);
        // الاستمرار بتنفيذ الحلقة
        $loop->run();
    }

    // رد نداء يُستدعى عندما يصبح المقبس قابلًا للقراءة
    public function _onReadable(EvIo $w) {
        // استقبال 20 بايت في وضع عدم التعطيل
        $ret = socket_recv($this->socket, $out, 20, MSG_DONTWAIT);

        if ($ret) {
            // إذا كان لا يزال هناك بيانات للقراءة، أضفها إلى المخزن المؤقت
            $this->buffer .= $out;
        } elseif ($ret === 0) {
            // إذا قُرِأت كل البيانات
            printf("\n<<<<\n%s\n>>>>", rtrim($this->buffer));
            fflush(STDOUT);
            $w->stop();
            $this->close();
            return;
        }

        // ‫التقاط EINPROGRESS، ‏EAGAIN أو EWOULDBLOCK
        if (in_array(socket_last_error(), static::$e_nonblocking)) {
            return;
        }
        $w->stop();
        $this->close();
    }
}

/////////////////////////////////////
class MyHttpClient {
    // ‫مصفوفة كائنات من الصنف MyHttpRequest
    private $requests = [];
    ?// ‫متغير من الصنف EvLoop
    private $loop;

    public function __construct() {
        // ‫ينفذ كل عميل HTTP حلقة حدث خاصة به
        $this->loop = new EvLoop();
    }

    public function __destruct() {
        $this->loop->stop();
    }

    // ‫تعيد هذه الدالة كائن EvLoop
    public function getLoop() {
        return $this->loop;
    }

    // إضافة طلبات معلقة
    public function addRequest(MyHttpRequest $r) {
        $this->requests []= $r;
    }

    // إرسال كل الطلبات المعلقة
    public function run() {
        $this->loop->run();
    }
}

//// الاستخدام
$client = new MyHttpClient();
foreach (range(1, 10) as $i) {
    $client->addRequest(new MyHttpRequest($client, 'my-host.local', '/test.php?a=' . $i, 'GET'));
}

$client->run();

في الموضع (1) معاملات الدالة هي:

• ‎$client من الصنف MyHttpClient.
• ‎$host اسم المضيف مثل google.co.uk، سلسلة نصية
• ‎$resource مورد HTTP مثل ‎/page?a=b&c=d، سلسلة نصية.
• ‎$method طريقة HTTP مثل: GET، ‏HEAD، ‏POST، ‏PUT…، سلسلة نصية. ترمي هذه الدالة الاستثناء RuntimeException.

الاختبار: بفرض أنّ سكربت http://my-host.local/test.php يطبع محتويات ‎$_GET:

<?php
echo 'GET: ', var_export($_GET, true), PHP_EOL;

سيكون عندها خرج الأمر php http-client.php مشابهًا للتالي:

<<<<
HTTP/1.1 200 OK
Server: nginx/1.10.1
Date: Fri, 02 Dec 2016 12:39:54 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: close
X-Powered-By: PHP/7.0.13-pl0-gentoo

1d
GET: array (
    'a' => '3',
)

0
>>>>
<<<<
HTTP/1.1 200 OK
Server: nginx/1.10.1
Date: Fri, 02 Dec 2016 12:39:54 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: close
X-Powered-By: PHP/7.0.13-pl0-gentoo

1d
GET: array (
    'a' => '2',
)
0
>>>>
...

// الخرج مختصر

لاحظ أنّ إضافة المقابس في PHP 5 قد تسجل تحذيرات لقيم الخطأ EINPROGRESS وEAGAIN وEWOULDBLOCK، من الممكن تعطيل هذه التسجيلات بكتابة الشيفرة:

error_reporting(E_ERROR);

استخدام حلقة الحدث Amp

تستفاد مكتبة العمل Amp من الوعود (اسم آخر لكائنات Awaitables) والمولِّدات لإنشاء نمط مشترك.

require __DIR__ . '/vendor/autoload.php';

use Amp\Dns;

// جرب الأسرع محللنا المعرّف من قِبل النظام أو غوغل
function queryStackOverflow($recordtype) {
    $requests = [
        Dns\query("stackoverflow.com", $recordtype),
        Dns\query("stackoverflow.com", $recordtype, ["server" => "8.8.8.8"]),
    ];

    // تعيد وعدًا ينتهي عندما ينتهي أول طلب
    return yield Amp\first($request);
}
\Amp\run(function() {
    // الحلقة الأساسية، نمط مشترك ضمنيًا
    try {
        // التحويل إلى نمط مشترك باستخدام Amp\resolve()‎
        $promise = Amp\resolve(queryStackOverflow(Dns\Record::NS));
        list($ns, $type, $ttl) =
        // ‫نحتاج إلى نتيجة NS واحدة وليس كل النتائج
        current(yield Amp\timeout($promise, 2000 /* milliseconds */));
        echo "The result of the fastest server to reply to our query was $ns";
    } catch (Amp\TimeoutException $e) {
        echo "We've heard no answer for 2 seconds! Bye!";
    } catch (Dns\NoRecordException $e) {
        echo "No NS records there? Stupid DNS nameserver!";
    }
});

التوطين (Localization)

توطين السلاسل النصية مع gettext()‎

gettext من مكتبة GNU هي إضافة PHP يجب تضمصينها ضمن ملف php.ini:

extension=php_gettext.dll #Windows
extension=gettext.so #Linux

تنفذ دوال gettext واجهة برمجة تطبيقات دعم اللغة الأصلية (NLS) والتي يمكن استخدامها لتوطين تطبيقات PHP.

يمكن إجراء السلاسل النصية للترجمة في PHP بضبط المحلية (locale) وضبط جداول الترجمة واستدعاء gettext()‎ على أي سلسلة نصية تريد ترجمتها.

<?php
// ضبط اللغة إلى الفرنسية
putenv('LC_ALL= fr_FR');
setlocale(LC_ALL, 'fr_FR');

// ‫تحديد موقع جداول الترجمة للنطاق 'myPHPApp'
bindtextdomain("myPHPApp", "./locale");

// ‫اختيار النطاق 'myPHPApp'
textdomain("myPHPApp");

الملف myPHPApp.po:

#: /Hello_world.php:56
msgid "Hello"
msgstr "Bonjour"

#: /Hello_world.php:242
msgid "How are you?"
msgstr "Comment allez-vous?"

تحمّل الدالة gettext()‎ ملف ‎.po بعد تصريفه أي ملف ‎.mo، الذي يربط ملفك ليصبح سلاسل نصية مترجمة كما في الأعلى.

بعد هذه الشيفرة البسيطة سيُنظر إلى الترجمة في الملف التالي:

./locale/fr_FR/LC_MESSAGES/myPHPApp.mo

عندما تستدعي gettext('some string')‎، إذا كانت السلسلة النصية 'some string' مُترجمة في الملف ‎.mo ستُرجع الترجمة وإلا ستُرجع السلسلة 'some string' غير مترجمة.

// ‫طباعة النسخة المترجمة من 'Welcome to My PHP Application'
echo gettext("Welcome to My PHP Application");

// ‫أو نستخدم الاسم البديل `‎_()‎` للدالة `gettext()‎`
echo _("Have a nice day");

معالجة الترويسات

الضبط الأساسي للترويسة

إليك الضبط الأساسي لترويسة للانتقال إلى صفحة جديدة عند الضغط على زر:

if(isset($_REQUEST['action']))
{
    switch($_REQUEST['action'])
    { // ضبط الترويسة بالاعتماد على أي الزر المضغوط
        case 'getState':
            header("Location: http://NewPageForState.com/getState.php?search=" . $_POST['search']);
            break;
        case 'getProject':
            header("Location: http://NewPageForProject.com/getProject.php?search=" . $_POST['search']);
        break;
    }
else
{
    GetSearchTerm(!NULL);
}
// نماذج لإضافة ولاية أو مشروع والضغط على البحث
function GetSearchTerm($success)
{
    if (is_null($success))
    {
        echo "<h4>You must enter a state or project number</h4>";
    }
    echo "<center><strong>Enter the State to search for</strong></center><p></p>";
// ‫استخدام `‎$_SERVER['PHP_SELF']‎` يبقينا في الصفحة حتى تقرر تعليمة `switch` أين سنذهب
    echo "<form action='" . $_SERVER['PHP_SELF'] . "' enctype='multipart/form-data' method='POST'>
<input type='hidden' name='action' value='getState'>
<center>State: <input type='text' name='search' size='10'></center><p></p>
<center><input type='submit' name='submit' value='Search State'></center>
</form>";
    GetSearchTermProject($success);
}
function GetSearchTermProject($success)
{
    echo "<center><br><strong>Enter the Project to search for</strong></center><p></p>";
    echo "<form action='" . $_SERVER['PHP_SELF'] . "' enctype='multipart/form-data' method='POST'>
<input type='hidden' name='action' value='getProject'>
<center>Project Number: <input type='text' name='search' size='10'></center><p></p>
<center><input type='submit' name='submit' value='Search Project'></center>
</form>";
}
?>

كيفية كشف عنوان IP لعميل

الاستخدام المناسب للترويسة HTTPXFORWARDED_FOR

يوجد متغير آخر يُستخدم بشكلٍ سيء على نطاق واسع في ضوء أحدث ثغرات httpoxy، تُستخدم الترويسة HTTP_X_FORWARDED_FOR غالبًا لكشف عنوان IP لعميل، لكن قد يؤدي ذلك بدون أي عمليات تحقق إضافية إلى مشاكل في الأمان خاصةً عند استخدام عنوان IP هذا لاحقًا للمصادقة أو في استعلامات SQL بدون تعقيم.

تتجاهل معظم أمثلة الشيفرة المتوفرة حقيقة أنّه يمكن أن نعد HTTP_X_FORWARDED_FOR معلومةً يوفرها العميل بنفسه ولذا فهي مصدر غير موثوق لاكتشاف عنوان IP العميل، تضيف بعض هذه الأمثلة تحذيرًا بشأن سوء الاستخدام المحتمل لكنها لا تزال تفتقد إلى القيام بالتحقق في شيفرتها، لذا نقدم لك مثالًا عن دالة مكتوبة في PHP عن كيفية كشف عنوان IP لعميل إذا كنت تعرف أنّ العميل يستخدم وكيلًا (proxy) وأنت تعرف أنّه يمكن الوثوق بهذا الوكيل، إذا لم تكن تعرف أي وكيل موثوق فيمكنك استخدام REMOTE_ADDR فقط.

function get_client_ip()
{
    // لا يوجد شيء لفعله بدون معلومات موثوقة
    if (!isset($_SERVER['REMOTE_ADDR'])) {
        return NULL;
    }

    // ‫الترويسة التي يستخدمها الوكيل الموثوق للإشارة إلى عنوان IP الأصلي
    $proxy_header = "HTTP_X_FORWARDED_FOR";

    // (1)
    $trusted_proxies = array("2001:db8::1", "192.168.50.1");

    if (in_array($_SERVER['REMOTE_ADDR'], $trusted_proxies)) {
        // ‫الحصول على عنوان IP للعميل الذي يستخدم وكيل موثوق
        if (array_key_exists($proxy_header, $_SERVER)) {
            // (2)
            $client_ip = trim(end(explode(",", $_SERVER[$proxy_header])));

            // التحقق فقط في حالة
            if (filter_var($client_ip, FILTER_VALIDATE_IP)) {
                return $client_ip;
            } else {
                // (3)
            }
        }
    }

    // ‫في كل الحالات الباقية REMOTE_ADDR هو عنوان IP الوحيد الذي يمكن الوثوق به
    return $_SERVER['REMOTE_ADDR'];
}
print get_client_ip();

في الموضع (1) نضيف قائمة بكل الوكلاء المعروفين لمعالجة 'proxy_header' بطريقةٍ آمنةٍ.

في الموضع (2) يمكن أن تحتوي الترويسة على عدة عناوين IP لوكلاء تمر عبرها، يمكن الوثوق فقط بعنوان IP الذي أضافه الوكيل الأخير (الموجود في القائمة).

في الموضع (3) فشل التحقق مما يعني فوز الشخص الذي ضَبط الوكيل أو أنشأ قائمة الوكلاء الموثوقين لذا يجب إضافة معالجة للأخطاء هنا والتنبيه على خطأ الشخص المسؤول.

ترجمة -وبتصرف- للفصول [Coding Conventions - Asynchronous programming - Localization - Headers Manipulation - How to Detect Client IP Address] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: معالجة الصور مع مكتبة GD ومكتبة Imagick في PHP
• المقال السابق: التعامل مع واجهة سطر الأوامر (CLI) في PHP

معالجة خيارات البرنامج

يمكن معالجة خيارات البرنامج باستخدام الدالة getopt()‎، التي تعمل بصيغة مشابهة للأمر getopt في معايير POSIX مع دعم إضافي للخيارات الطويلة ذات النمط GNU.

#!/usr/bin/php

// تشير النقطتين إلى خيار يأخذ قيمة
// تشير النقطتين المضاعفتين إلى قيمة يمكن إهمالها
$shortopts = "hf:v::d";

// ‫الخيارات الطويلة ذات النمط GNU غير مطلوبة
$longopts = ["help", "version"];
$opts = getopt($shortopts, $longopts);

// ‫تُسند القيمة المنطقية false للخيارات التي ليس لها قيم، يجب التحقق من وجودها وليس صدقها
if (isset($opts["h"]) || isset($opts["help"])) {
    fprintf(STDERR, "Here is some help!\n");
    exit;
}

// ‫تُستدعى الخيارات الطويلة مع شرطتين: "‎--version"
if (isset($opts["version"])) {
    fprintf(STDERR, "%s Version 223.45" . PHP_EOL, $argv[0]);
exit;
}

// ‫يمكن استدعاء الخيارات ذات القيم بالشكل "‎-f foo" أو ‏"‎-ffoo" أو "‎-f=foo"
$file = "";
if (isset($opts["f"])) {
    $file = $opts["f"];
}
if (empty($file)) {
    fprintf(STDERR, "We wanted a file!" . PHP_EOL);
    exit(1);
}
fprintf(STDOUT, "File is %s" . PHP_EOL, $file);

// ‫يمكن استدعاء الخيارات ذات القيم الافتراضية بالشكل "‎-v5" أو "‎-v=5"
$verbosity = 0;
if (isset($opts["v"])) {
    $verbosity = ($opts["v"] === false) ? 1 : (int)$opts["v"];
}
fprintf(STDOUT, "Verbosity is %d" . PHP_EOL, $verbosity);

// تُمرَّر الخيارات التي نستدعيها عدة مرات كمصفوفة
$debug = 0;
if (isset($opts["d"])) {
    $debug = is_array($opts["d"]) ? count($opts["d"]) : 1;
}
fprintf(STDOUT, "Debug is %d" . PHP_EOL, $debug);

// ‫لا توجد طريقة تلقائية عند getopt لمعالجة الخيارات غير المتوقعة

يمكن اختبار السكربت السابق بالشكل:

./test.php --help
./test.php --version
./test.php -f foo -ddd
./test.php -v -d -ffoo
./test.php -v5 -f=foo
./test.php -f foo -v 5 -d

لاحظ أنّ الطريقة الأخيرة لن تعمل لأنّ ‎-v 5 غير صحيحة.

ملاحظة: يعدّ الأمر getopt بدءًا من الإصدار PHP 5.3.0 مستقلًا عن نظام التشغيل ويعمل أيضًا على نظام ويندوز.

معالجة الوسيط

تُمرَّر الوسائط إلى البرنامج بطريقة مشابهة لمعظم اللغات ذات النمط C، إنّ ‎$argc عدد صحيح يعبّر عن عدد الوسائط متضمنةً اسم البرنامج و‎$argv مصفوفة تتضمن وسائط البرنامج. العنصر الأول من ‎$argv هو اسم البرنامج.

#!/usr/bin/php
printf("You called the program %s with %d arguments\n", $argv[0], $argc - 1);
unset($argv[0]);
foreach ($argv as $i => $arg) {
    printf("Argument %d is %s\n", $i, $arg);
}

استدعاء التطبيق السابق باستخدام php example.php foo bar (حيث يتضمن الملف example.php الشيفرة السابقة) سيؤدي إلى الخرج التالي:

You called the program example.php with 2 arguments
Argument 1 is foo
Argument 2 is bar

لاحظ أنّ ‎$argc و‎$argv هي متغيرات عامة وليست متغيرات ذات نطاق عام عالي، ويجب استيرادها إلى النطاق المحلي باستخدام الكلمة المفتاحية global عندما نحتاج إلى استخدامها في دالة ما.

يُظهر هذا المثال كيف تُجمَّع الوسائط عندما نهرب باستخدام "" أو \.

مثال عن سكربت:

var_dump($argc, $argv);

سطر الأوامر:

$ php argc.argv.php --this-is-an-option three\ words\ together or "in one quote" but\ multiple\spaces\ counted\ as\ one
int(6)
array(6) {
    [0]=>
    string(13) "argc.argv.php"
    [1]=>
    string(19) "--this-is-an-option"
    [2]=>
    string(20) "three words together"
    [3]=>
    string(2) "or"
    [4]=>
    string(12) "in one quote"
    [5]=>
    string(34) "but multiple spaces counted as one"
}

إذا نُفِّذ سكربت PHP باستخدام ‎-r:

$ php -r 'var_dump($argv);'
array(1) {
    [0]=>
    string(1) "-"
}

أو تُرسل الشيفرة عبر أنبوب في مجرى الدخل القياسي php:

$ echo '<?php var_dump($argv);' | php
array(1) {
    [0]=>
    string(1) "-"
}

معالجة الدخل والخرج

إنّ الثوابت STDIN وSTDOUT وSTDERR معرَّفة مسبقًا عند التنفيذ من واجهة سطر الأوامر (CLI)، وهي مقابض للملف يمكن أن نعدّها مكافئة لنتائج تنفيذ الأوامر التالية:

STDIN = fopen("php://stdin", "r");
STDOUT = fopen("php://stdout", "w");
STDERR = fopen("php://stderr", "w");

يمكن استخدام الثوابت في أي مكان يكون مقبض الملف القياسي فيه:

#!/usr/bin/php

while ($line = fgets(STDIN)) {
    $line = strtolower(trim($line));
    switch ($line) {
        case "bad":
        fprintf(STDERR, "%s is bad" . PHP_EOL, $line);
        break;
        case "quit":
        exit;
        default:
        fprintf(STDOUT, "%s is good" . PHP_EOL, $line);
        break;
    }
}

يمكن استخدام عناوين المجرى المضمَّن المُشار إليها سابقًا php://stdin وphp://stdout وphp://stderr مكان أسماء الملفات في معظم الحالات:

file_put_contents('php://stdout', 'This is stdout content');
file_put_contents('php://stderr', 'This is stderr content');

// فتح المقبض والكتابة عدة مرات
$stdout = fopen('php://stdout', 'w');
fwrite($stdout, 'Hello world from stdout' . PHP_EOL);
fwrite($stdout, 'Hello again');

fclose($stdout);

يمكن أن تستخدم أيضًا الدالة readline()‎ كبديل للدخل وتستخدم echo أو print أو أي دالة من دوال طباعة السلسلة النصية كبديل للخرج.

$name = readline("Please enter your name:");
print "Hello, {$name}.";

الشيفرات المُعادة

يمكن استخدام البنية exit لتمرير شيفرة معادة إلى بيئة التنفيذ.

#!/usr/bin/php
if ($argv[1] === "bad") {
    exit(1);
} else {
    exit(0);
}

ستُرجَع شيفرة الخروج 0 بشكلٍ افتراضي إذا لم تُمرَّر قيمة أي أنّ exit نفس exit(0)‎ وبما أنّ exit ليست دالة فإنّ الأقواس غير ضرورية إذا لم تُمرَّر شيفرة معادة.

يجب أن تكون الشيفرات المُعادة في المجال بين 0 و254 (الشيفرة 255 محجوزة من قِبَل PHP ويجب عدم استخدامها)، اصطلاحًا إنّ الخروج بالشيفرة المُرجعة 0 تُخبر البرنامج المُستدعي أنّ سكربت PHP نُفِّذ بنجاح أما الشيفرة المرجعية غير الصفرية تُخبر البرنامج المستدعي بحدوث حالة خطأ محددة.

قصر تنفيذ السكربت على سطر الأوامر

يُرجع كل من الدالة php_sapi_name()‎ والثابت PHP_SAPI نوع الواجهة (واجهة برمجة تطبيقات الخادم Server API) التي تستخدمها PHP، ويمكن استخدامها لقصر تنفيذ السكربت على سطر الأوامر عن طريق التحقق فيما إذا كان خرج الدالة يساوي cli.

if (php_sapi_name() === 'cli') {
    echo "Executed from command line\n";
} else {
    echo "Executed from web browser\n";
}

الدالة drupal_is_cli()‎ هي مثال عن دالة تكتشف فيما إذا كان السكربت قد نُفِّذ من سطر الأوامر:

function drupal_is_cli() {
    return (!isset($_SERVER['SERVER_SOFTWARE']) && (php_sapi_name() == 'cli' || (is_numeric($_SERVER['argc']) && $_SERVER['argc'] > 0)));
}

الاختلافات السلوكية في سطر الأوامر

تعرض PHP عند التنفيذ من CLI بعض السلوكيات المختلفة عن السلوكيات عند التنفيذ على خادم ويب، يجب أن تتذكر هذه السلوكيات خاصةً في حالة تنفيذ نفس السكربت في البيئتين.

• لا يتغير المجلد عند التنفيذ على خادم ويب بل يبقى مجلد العمل الحالي للسكربت نفسه دائمًا، تفترض الشيفرة require("./stuff.inc");‎ أنّ الملف في نفس مجلد السكربت، أما في سطر الأوامر فإنّ مجلد العمل الحالي هو المجلد الذي يُستدعى منه السكربت، يجب أن تستخدم السكربتات التي ستُستدعى من سطر الأوامر مسارات مطلقة. (لاحظ أنّ الثوابت السحرية __DIR__ و__FILE__ تبقى تعمل كما هو متوقع وتُرجع موقع السكربت).
• لا يوجد مخزن مؤقت للخرج، القيم الافتراضية لموجهات الملف php.ini ‏output_buffering وimplicit_flush هي false وtrue على الترتيب. ويبقى المخزن المؤقت متوفرًا لكن يجب تمكينه بشكلٍ صريح وإلا سيُعرض الخرج دائمًا في الوقت الحقيقي.
• لا يوجد قيد زمني، يُضبط الموجه max_execution_time في الملف php.ini إلى القيمة صفر لذا لن ينتهي وقت تنفيذ السكربتات بشكلٍ افتراضي.
• لا توجد أخطاء HTML، إذا مكّنت الموجّه html_errors في ملف php.ini سيتجاهله سطر الأوامر.
• يمكن تحميل ملفات php.ini مختلفة، إذا كنت تستخدم PHP من CLI يمكنك تحميل ملفات php.ini مختلفة وهذا غير متاح عند التنفيذ على خادم ويب، يمكنك أن تعرف ما هو الملف المستخدم بتنفيذ الأمر php ‎--ini‎.

تنفيذ السكربت

في كل من لينوكس/يونكس أو ويندوز يمكن تمرير الملف كوسيط إلى PHP القابلة للتنفيذ مع خيارات ووسائط السكربت:

php ~/example.php foo bar

c:\php\php.exe c:\example.php foo bar

تمرر الشيفرة السابقة الوسائط foo وbar إلى الملف example.php.

الطريقة المفضلة لتنفيذ السكربتات في لينوكس/يونكس هي استخدام Shebang (سطر يبدأ بالسلسلة النصية "‎ #! ‎") مثل ‎#!/usr/bin/env php في السطر الأول من الملف وضبط البت القابل للتنفيذ على الملف، بفرض أنّ السكربت في مسارك يمكنك عندها استدعاؤه مباشرةً:

example.php foo bar

إنّ استخدام ‎/usr/bin/env php‎ يجعل من الممكن العثور على PHP القابلة للتنفيذ باستخدام PATH. وفقًا لكيفية تثبيت PHP قد لا تكون موجودة في نفس المكان (مثل ‎/usr/bin/php‎ أو ‎/usr/local/bin/php) على عكس env المتوفرة عادةً في ‎/usr/bin/env.

في ويندوز قد تحصل على نفس النتيجة بإضافة مجلد PHP والسكربت الخاص بك إلى PATH وتعديل PATHEXT ليسمح باكتشاف ‎.php باستخدام PATH، الاحتمال الآخر هو إضافة ملف باسم example.bat أو example.cmd في نفس المجلد الموجود به سكربت PHP وكتابة هذا السطر فيه:

c:\php\php.exe "%~dp0example.php" %*

أو إذا أضفت مجلد PHP داخل PATH:

php "%~dp0example.php" %*

حالات متقدمة لاستخدام getopt()‎

يظهر هذا المثال سلوك getopt عندما يكون دخل المستخدم غير شائع، محتويات الملف getopt.php:

var_dump(
    getopt("ab:c::", ["delta", "epsilon:", "zeta::"])
);

سطر أوامر الصدفة:

$ php getopt.php -a -a -bbeta -b beta -cgamma --delta --epsilon --zeta --zeta=f -c gamma
array(6) {
    ["a"]=>
    array(2) {
        [0]=>
        bool(false)
        [1]=>
        bool(false)
    }
    ["b"]=>
    array(2) {
        [0]=>
        string(4) "beta"
        [1]=>
        string(4) "beta"
    }
    ["c"]=>
    array(2) {
        [0]=>
        string(5) "gamma"
        [1]=>
        bool(false)
    }
    ["delta"]=>
        bool(false)
    ["epsilon"]=>
        string(6) "--zeta"
    ["zeta"]=>
        string(1) "f"
}

يمكننا أن نلاحظ من المثال السابق:

• تحمل الخيارات الفردية (بدون نقطتان) دائمًا القيمة المنطقية false إذا مُكِّنت.
• إذا كُرِّر خيار ما فإنّ قيمة خرج getopt ستصبح مصفوفة.
• تقبل خيارات الوسيط المطلوب (بنقطتين) فراغ واحد أو عدم وجود فراغ (مثل خيارات الوسيط الاختيارية) كفاصل.
• بعد وجود وسيط واحد لا يمكن ربطه بأي خيار فإنّ الخيارات التالية لن تُربط أيضًا.

تشغيل خادم ويب مدمج

أصبحت PHP بدءًا من الإصدار PHP 5.4 تأتي مع خادم مدمج، يمكن استخدامه لتنفيذ تطبيق بدون الحاجة لتثبيت أي خادم http مثل nginx أو apache، صُمم الخادم المدمج في بيئة المتحكم فقط لأهداف التطوير والاختبار، يمكن تنفيذه باستخدام الأمر php -S ولاختباره ننشئ الملف index.php ونكتب فيه:

<?php
echo "Hello World from built-in PHP server";

وننفذ الأمر:

php -S localhost:8080

يجب أن تكون الآن قادرًا على رؤية المحتوى في المتصفح، للتحقق من ذلك انتقل إلى المسار http://localhost:8080 ، ويجب أن يؤدي كل وصول إلى مدخل سجل يُكتب في الطرفية (Terminal).

[Mon Aug 15 18:20:19 2016] ::1:52455 [200]: /

ترجمة -وبتصرف- للفصل [Command Line Interface (CLI)‎] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: اصطلاحات ومواضيع متفرقة مهمة لكل مبرمج PHP
• المقال السابق: ملاحظات حول استعمال بروتوكول IMAP في PHP

الاتصال إلى صندوق البريد (mailbox)

للقيام بأي فعل مع حساب IMAP (‏Internet Message Access Protocol) تحتاج للاتصال به أولًا، ولتتصل تحتاج لتحديد بعض المعاملات المطلوبة:

• اسم الخادم أو عنوان IP لخادم البريد (mail server).
• المنفذ الذي تريد الاتصال به:
  • منفذ IMAP هو 143 أو993 (آمن).
  • منفذ POP (‏Post Office Protocol‏) هو 110 أو995 (آمن).
  • منفذ SMTP (‏Simple Mail Transfer Protocol) هو 25 أو465 (آمن).
  • منفذ NNTP (‏Network News Transfer Protocol) هو 119 أو563 (آمن).
• رايات الاتصال: موضحة في الجدول التالي:

ستبدو سلسلة الاتصال بالشكل التالي:

{imap.example.com:993/imap/tls/secure}

لاحظ أنّه إذا كان أي محرف في سلسة الاتصال غير مرمّز بالترميز ASCII فيجب ترميزه باستخدام utf7_encode($string)‎.

نستخدم الأمر imap open للاتصال إلى صندوق البريد، يعيد هذا الأمر قيمة مورد تشير إلى مجرى:

<?php
$mailbox = imap_open("{imap.example.com:993/imap/tls/secure}", "username", "password");
if ($mailbox === false) {
    echo "Failed to connect to server";
}

تحميل الإضافة IMAP

نحتاج لتثبيت الإضافة IMAP حتى نتمكن من استخدام دوال IMAP في PHP.

التثبيت في نظام ديبيان/أبونتو مع PHP5

sudo apt-get install php5-imap
sudo php5enmod imap

التثبيت في نظام ديبيان/أبونتو مع PHP5

sudo apt-get install php7.0-imap

التثبيت في التوزيعات المعتمدة على YUM

sudo yum install php-imap

التثبيت في إصدارات نظام التشغيل ماك مع php5.6

brew reinstall php56 --with-imap

إنشاء قائمة بكل مجلدات صندوق البريد

عندما تتصل بصندوق البريد الخاص بك، سترغب في إلقاء نظرة بداخله، الأمر الأول المفيد في هذه الحالة هو imap list، المعامل الأول هو المورد الذي حصلت عليه من imap_open والثاني هو صندوق البريد الخاص بك والثالث سلسلة بحث غامضة (نستخدم * لمطابقة أي نمط).

$folders = imap_list($mailbox, "{imap.example.com:993/imap/tls/secure}", "*");
if ($folders === false) {
    echo "Failed to list folders in mailbox";
} else {
    print_r($folders);
}

يجب أن يكون الخرج مشابهًا للتالي:

Array
(
    [0] => {imap.example.com:993/imap/tls/secure}INBOX
    [1] => {imap.example.com:993/imap/tls/secure}INBOX.Sent
    [2] => {imap.example.com:993/imap/tls/secure}INBOX.Drafts
    [3] => {imap.example.com:993/imap/tls/secure}INBOX.Junk
    [4] => {imap.example.com:993/imap/tls/secure}INBOX.Trash
)

يمكننا استخدام المعامل الثالث لترشيح هذه النتائج بالشكل التالي:

$folders = imap_list($mailbox, "{imap.example.com:993/imap/tls/secure}", "*.Sent");

عندها ستحتوي النتيجة على المداخل التي فيها السلسلة النصية ‎.Sent في الاسم:

Array
(
    [0] => {imap.example.com:993/imap/tls/secure}INBOX.Sent
)

ملاحظة: سيعيد استخدام * للبحث الغامض كل التطابقات بشكلٍ متكرر، ويعيد استخدام % التطابقات في المجلد الحالي المحدد فقط.

البحث عن الرسائل في صندوق البريد

يمكنك أن تستخدم imap_headers لتحصل على قائمة بكل الرسائل الموجودة في صندوق البريد.

<?php
$headers = imap_headers($mailbox);

تكون النتيجة مصفوفة من السلاسل النصية بالنمط التالي:

[FLAG] [MESSAGE-ID])[DD-MM-YYY] [FROM ADDRESS] [SUBJECT TRUNCATED TO 25 CHAR] ([SIZE] chars)

إليك عينة عن الشكل الذي سيبدو عليه كل سطر:

A     1)19-Aug-2016 someone@example.com Message Subject (1728 chars)
D     2)19-Aug-2016 someone@example.com RE: Message Subject (22840 chars)
U     3)19-Aug-2016 someone@example.com RE: RE: Message Subject (1876 chars)
N     4)19-Aug-2016 someone@example.com RE: RE: RE: Message Subje (1741 chars)

لاحظ أنّ هذا الاستدعاء سيأخذ بعض الوقت ليُنفَّذ وقد يعيد قائمة طويلة جدًا، الخيار البديل هو تحميل الرسائل بشكلٍ منفصل وفقًا للحاجة، يُسند معرِّف لكل بريد إلكتروني من الرقم 1 (الأقدم) وحتى قيمة imap_num_msg($mailbox)‎.

يوجد عدة دوال للوصول إلى بريد إلكتروني مباشرةً، لكن أبسط طريقة هي استخدام الدالة imap_header التي تُرجع معلومات ترويسة مهيكلة:

<?php
$header = imap_headerinfo($mailbox , 1);
stdClass Object
(
    [date] => Wed, 19 Oct 2011 17:34:52 +0000
    [subject] => Message Subject
    [message_id] => <04b80ceedac8e74$51a8d50dd$0206600a@user1687763490>
    [references] => <ec129beef8a113c941ad68bdaae9@example.com>
    [toaddress] => Some One Else <someoneelse@example.com>
    [to] => Array
        (
            [0] => stdClass Object
                (
                    [personal] => Some One Else
                    [mailbox] => someonelse
                    [host] => example.com
                )
        )
    [fromaddress] => Some One <someone@example.com>
    [from] => Array
        (
            [0] => stdClass Object
                (
                    [personal] => Some One
                    [mailbox] => someone
                    [host] => example.com
                )
        )
    [reply_toaddress] => Some One <someone@example.com>
    [reply_to] => Array
        (
            [0] => stdClass Object
                (
                    [personal] => Some One
                    [mailbox] => someone
                    [host] => example.com
                )
        )
    [senderaddress] => Some One <someone@example.com>
    [sender] => Array
        (
            [0] => stdClass Object
                (
                    [personal] => Some One
                    [mailbox] => someone
                    [host] => example.com
                )
        )
    [Recent] =>
    [Unseen] =>
    [Flagged] =>
    [Answered] =>
    [Deleted] =>
    [Draft] =>
    [Msgno] => 1
    [MailDate] => 19-Oct-2011 17:34:48 +0000
    [Size] => 1728
    [udate] => 1319038488
)

ترجمة -وبتصرف- للفصول [IMAP] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: التعامل مع واجهة سطر الأوامر (CLI) في PHP
• المقال السابق: كيفية إرسال بريد إلكتروني في PHP

معاملات الدالة mail()‎ في PHP:

أساسيات إرسال بريد إلكتروني مع مثال

يتألف البريد الإلكتروني النموذجي من ثلاثة مكونات أساسية:

• مُستقبِل (يُمثَّل كعنوان بريد إلكتروني)
• موضوع
• جسم الرسالة

يمكن أن يكون إرسال بريد إلكتروني بسيطًا مثل استدعاء الدالة المضمنة mail()‎، تأخذ هذه الدالة حتى 5 معاملات، أول ثلاث معاملات هي المطلوبة فقط لإرسال بريد إلكتروني (ومن الشائع استخدام المعامل الرابع كما سنوضح في المثال أدناه)، المعاملات الثلاثة الأولى هي:

• عنوان البريد الإلكتروني للمستقبل (سلسلة نصية).
• موضوع البريد الإلكتروني (سلسلة نصية).
• جسم البريد الإلكتروني (سلسلة نصية) (أي محتوى البريد الإلكتروني).

الشيفرة التالية توضح مثال بسيط:

mail('recipient@example.com', 'Email Subject', 'This is the email message body');

يعدّ المثال السابق جيدًا في بعض الحالات مثل توفير القيمة في شيفرة (بدلًا من جلبها من مصدر خارجي) عند إرسال بريد إلكتروني للتنبيه في نظام داخلي. لكن من الشائع وضع المعاملات الممررة كمعاملات للدالة mail()‎ في متغيرات لجعل الشيفرة أنظف وأسهل في الإدارة (مثلًا لإنشاء بريد إلكتروني ديناميكي بعد إرسال نموذج).

بالإضافة إلى ذلك تقبل الدالة mail()‎ معاملًا رابعًا يسمح لك بإضافة ترويسات في البريد الإلكتروني المرسل، يمكن أن تسمح لك هذه الترويسات بضبط:

• اسم المرسل وعنوان البريد الإلكتروني الذي سيظهر لدى المستخدم.
• عنوان البريد الإلكتروني للحقل Reply-To والذي سيُرسل إليه رد المستخدم.
• ترويسات إضافية غير معيارية مثل X-Mailer والتي تخبر المستقبل أن هذا البريد الإلكتروني أُرسل عبر PHP.

// ‫يمكن أن تكون ‎$to = $_POST['recipient'];‎
$to = 'recipient@example.com';

// ‫يمكن أن تكون ‎$subject = $_POST['subject'];‎
$subject = 'Email Subject';

// ‫يمكن أن تكون ‎$message = $_POST['message'];‎
$message = 'This is the email message body';

$headers = implode("\r\n", [
    'From: John Conde <webmaster@example.com>',
    'Reply-To: webmaster@example.com',
    'X-Mailer: PHP/' . PHP_VERSION
]);

يمكن أن يُستخدم المعامل الخامس الاختياري لتمرير رايات إضافية مثل خيارات سطر الأوامر إلى البرنامج المُعدّ ليستخدم عند إرسال بريد إلكتروني كما هو معرَّف في ضبط الإعداد sendmail_path، يمكن استخدامه مثلًا لضبط عنوان المرسل عند استخدام الأمر sendmail/postfix مع الخيار ‎-f لإرسال بريد إلكتروني.

$fifth = '-fno-reply@example.com';

على الرغم من أن استخدام الدالة mail()‎ يمكن أن يكون موثوقًا إلى حد كبير، إلا أنّه لا يوجد ما يضمن إرسال البريد الإلكتروني عند كل استدعاء لها، لذا يجب أن تلتقط القيمة المُرجعة منها لتعرف ما إذا كان هناك خطأ محتمل عند إرسال بريدك الإلكتروني، إذ أنّ الدالة ستُرجع القيمة TRUE إذا قُبل البريد الإلكتروني بنجاح للتسليم وإلا ستُرجع القيمة FALSE.

$result = mail($to, $subject, $message, $headers, $fifth);

ملاحظة: إنّ إرجاع الدالة mail()‎ للقيمة TRUE لا يعني أنّ البريد الإلكتروني أُرسل أو أنّه سيُستقبَل بنجاح، إنما فقط يدل على أنّ البريد الإلكتروني سُلِّم بنجاح إلى نظام البريد الإلكتروني الخاص بك.

تحتاج إلى بعض الخطوات الإضافية لترسل بريد إلكتروني بصيغة HTML:

• إضافة الترويسة MIME-Version.
• إضافة الترويسة Content-Type.
• التأكد من أنّ محتوى البريد الإلكتروني بصيغة HTML.

$to = 'recipient@example.com';
$subject = 'Email Subject';
$message = '<html><body>This is the email message body</body></html>';
$headers = implode("\r\n", [
    'From: John Conde <webmaster@example.com>',
    'Reply-To: webmaster@example.com',
    'MIME-Version: 1.0',
    'Content-Type: text/html; charset=ISO-8859-1',
    'X-Mailer: PHP/' . PHP_VERSION
]);

إليك مثال كامل لاستخدام الدالة mail()‎:

// ‫أدوات تنقيح الأخطاء، شغّلها في بيئة التطوير الخاصة بك فقط.
error_reporting(-1);
ini_set('display_errors', 'On');
set_error_handler("var_dump");

// ‫إعدادات بريد إلكتروني خاصة يمكن أن تقلل من احتمال جعل البريد الإلكتروني الخاص بك غير مرغوب فيه وتوفر تسجيل دخول في حالة وجود صعوبات تقنية.
ini_set("mail.log", "/tmp/mail.log");
ini_set("mail.add_x_header", TRUE);

// مكونات بريدنا الإلكتروني
$to = 'recipient@example.com';
$subject = 'Email Subject';
$message = 'This is the email message body';
$headers = implode("\r\n", [
    'From: webmaster@example.com',
    'Reply-To: webmaster@example.com',
    'X-Mailer: PHP/' . PHP_VERSION
]);

// إرسال البريد الإلكتروني
$result = mail($to, $subject, $message, $headers);

// ‫التحقق من النتائج والتفاعل وفقًا لذلك.
if ($result) {
    // (1)
    header('Location: http://example.com/path/to/thank-you.php', true, 303);
    exit;
}
else {
    // (2)
}

في الموضع (1) تكون الدالة أرجعت القيمة TRUE وسيُعاد التوجيه إلى صفحة thank-you، نستخدم النمط POST/REDIRECT/GET لمنع إعادة إرسال النموذج عندما يحدّث المستخدم الصفحة.

في الموضع (2) لم يُرسل البريد الإلكتروني، تحقق من السجلات لمعرفة السبب.

يمكنك الاطلاع أيضًا على: التوثيق الرسمي:

• mail
• إعدادات الدالة mail

أسئلة ذات صلة من موقع stack overflow:

• الدالة mail لا تُكمل إرسال البريد الإلكتروني.
• كيف تتأكد من أنّ بريدك الإلكتروني المُرسل لا يُصنف ضمن البريد الإلكتروني غير المرغوب فيه.
• كيف تستخدم SMTP لإرسال بريد إلكتروني.
• ضبط إعدادات مرسل البريد الإلكتروني.

خدمات بريد إلكتروني بديلة:

• PHPMailer‏
• SwiftMailer
• PEAR::Mail

مخدمات بريد إلكتروني:

• Mercury Mail (Windows)

مواضيع ذات صلة:

• Post/Redirect/Get

إرسال بريد إلكتروني يحتوي على صيغة HTML باستخدام الدالة mail()‎

<?php
$to = 'recipent@example.com';
$subject = 'Sending an HTML email using mail() in PHP';
$message = '<html><body><p><b>This paragraph is bold.</b></p><p><i>This text is italic.</i></p></body></html>';

$headers = implode("\r\n", [
    "From: John Conde <webmaster@example.com>",
    "Reply-To: webmaster@example.com",
    "X-Mailer: PHP/" . PHP_VERSION,
    "MIME-Version: 1.0",
    "Content-Type: text/html; charset=UTF-8"
]);

mail($to, $subject, $message, $headers);

لا يختلف هذا كثيرًا عن إرسال بريد إلكتروني يحتوي على نص بسيط⁢، الاختلافات الرئيسة هي أنّ المحتوى عبارة عن ملف HTML ويوجد ترويستين إضافيتين يجب تضمينهما حتى يعرف البريد الإلكتروني للعميل أنّ البريد الإلكتروني بصيغة HTML وهما:

• MIME-Version: 1.0
• Content-Type: text/html; charset=UTF-8

إرسال بريد إلكتروني مع مرفق باستخدام الدالة mail()‎

إليك المثال التالي:

<?php
$to = 'recipient@example.com';
$subject = 'Email Subject';
$message = 'This is the email message body';
$attachment = '/path/to/your/file.pdf';
$content = file_get_contents($attachment);

// (1)
$content = chunk_split(base64_encode($content));

//(2)
$prefix = "part_"; // (3)

// (4)
$boundary = uniqid($prefix, true);

// الترويسات
$headers = implode("\r\n", [
    'From: webmaster@example.com',
    'Reply-To: webmaster@example.com',
    'X-Mailer: PHP/' . PHP_VERSION,
    'MIME-Version: 1.0',

    // معامل الحد مطلوب ويجب أن يكون ضمن علامات اقتباس
    'Content-Type: multipart/mixed; boundary="' . $boundary . '"',
    "Content-Transfer-Encoding: 7bit",
    "This is a MIME encoded message." // message for restricted transports
]);

// الرسالة والمرفق
$message = implode("\r\n", [
    "--" . $boundary, // (5)
    'Content-Type: text/plain; charset="iso-8859-1"',
    "Content-Transfer-Encoding: 8bit",
    $message,
    "--" . $boundary, // (6)
    'Content-Type: application/octet-stream; name="RenamedFile.pdf"',
    "Content-Transfer-Encoding: base64",
    "Content-Disposition: attachment",
    $content,
    "--" . $boundary . "--" // (7)
]);

// إرسال البريد الإلكتروني
$result = mail($to, $subject, $message, $headers); 

if ($result) {
    // (8)
    header('Location: http://example.com/path/to/thank-you.php', true, 303);
    exit;
}
else {
    // (9)
}

في الموضع (1) يجب تقسيم محتوى المرفق المُرسل باستخدام تشفير Base64 إلى أجزاء بطول 76 محرفًا كما هو محدد في القسم 6.8 من RFC 2045، تستخدم الدالة chunk_split()‎ بشكلٍ افتراضي طول الجزء 76 مع CRLF زائدة ‎(\r\n)‎، لا يتضمن متطلب 76 محرفًا المحارف carriage return وline feed.

في الموضع (2) تحدد الحدود الكيانات متعددة الأجزاء، يجب ألا يكون الحد في أي جزء مغلف كما هو مذكور في القسم 5.1 من RFC 2046 لذا يجب أن يكون فريدًا، وكما هو مذكور في القسم 5.1.1 التالي فإنّ الحدّ يُعرَّف على أنّه خط يتألف من موصلين ("--") وقيمة معامل ومسافة خطية اختيارية وCRLF نهائية.

في الموضع (3) بادئة اختيارية.

في الموضع (4) إنشاء قيمة معامل حد فريدة مع البادئة باستخدام الدالة uniqid()‎، المعامل الثاني يجعل قيمة المعامل فريدة أكثر.

في الموضع (5) محدد حد الترويسة

في الموضع (6) محدد حد المحتوى

في الموضع (7) محدد حد الإغلاق

في الموضع (8) تكون الدالة أرجعت القيمة TRUE وسيُعاد التوجيه إلى صفحة thank-you، نستخدم النمط POST/REDIRECT/GET لمنع إعادة إرسال النموذج عندما يحدّث المستخدم الصفحة.

في الموضع (9) لم يُرسل البريد الإلكتروني، تحقق من السجلات لمعرفة السبب.

ترميز نقل المحتوى

الترميزات المتاحة هي 7 بت، 8 بت، الثنائي، مقتبس قابل للطباعة (quoted-printable)، الأساس 64 (base64)، ‏ietf-token وx-token، من هذه الترميزات عندما يكون Content-Type متعدد الأجزاء فإنّ ترميز نقل المحتوى يجب ألّا يكون أي قيمة أخرى غير 7 بت أو 8 بت أو ثنائي.

نختار في مثالنا ترميز 7 بت الذي يمثّل محارف US-ASCII للترويسة متعددة الأجزاء لأنّ بعض البروتوكولات تدعم هذا الترميز فقط، ويمكن بعدها تشفير البيانات ضمن الحدود على أساس كل جزء على حدة، وهذا ما يفعله هذا المثال بالضبط. الجزء الأول الذي يتضمن رسالة من النوع text/plain يُعرَّف على أنّه 8 بت بما أنّه قد يكون من الضروري أن يدعم محارف إضافية، في هذه الحالة تُستخدم مجموعة المحارف Latin1 (iso-8859-1)‎، الجزء الثاني هو المرفق لذا يُعرَّف على أنّه بترميز الأساس 64 application/octet-stream. بما أنّ الأساس 64 يحوّل البيانات إلى المجال 7 بت، يمكن أن تُرسَل عبر عمليات نقل مقيدة.

إرسال بريد إلكتروني يحتوي على نص بسيط باستخدام PHPMailer

بريد إلكتروني يحتوي على نص بسيط

<?php
$mail = new PHPMailer();

$mail->From = "from@example.com";
$mail->FromName = "Full Name";
$mail->addReplyTo("reply@example.com", "Reply Address");
$mail->Subject = "Subject Text";
$mail->Body = "This is a sample basic text email using PHPMailer.";

if($mail->send()) {
    // (1)
    header('Location: http://example.com/path/to/thank-you.php', true, 303);
    exit;
}
else {
    echo "Mailer Error: " . $mail->ErrorInfo;
}

في الموضع (1) تكون الدالة أرجعت القيمة TRUE وسيُعاد التوجيه إلى صفحة thank-you، نستخدم النمط POST/REDIRECT/GET لمنع إعادة إرسال النموذج عندما يحدّث المستخدم الصفحة.

إضافة مستقبلين إضافيين، مستقبلين نسخة إضافية (CC)، مستقبلين نسخة إضافية محجوبين (BCC)

<?php
$mail = new PHPMailer();

$mail->From = "from@example.com";
$mail->FromName = "Full Name";
$mail->addReplyTo("reply@example.com", "Reply Address");
$mail->addAddress("recepient1@example.com", "Recepient Name");
$mail->addAddress("recepient2@example.com");
$mail->addCC("cc@example.com");
$mail->addBCC("bcc@example.com");
$mail->Subject = "Subject Text";
$mail->Body = "This is a sample basic text email using PHPMailer.";

if($mail->send()) {
    // (1)
    header('Location: http://example.com/path/to/thank-you.php', true, 303);
    exit;
}
else {
    echo "Error: " . $mail->ErrorInfo;
}

في الموضع (1) تكون الدالة أرجعت القيمة TRUE وسيُعاد التوجيه إلى صفحة thank-you، نستخدم النمط POST/REDIRECT/GET لمنع إعادة إرسال النموذج عندما يحدّث المستخدم الصفحة.

إرسال بريد إلكتروني باستخدام PHPMailer

إليك مثال عن إرسال بريد إلكتروني يحتوي على صيغة HTML باستخدام PHPMailer:

<?php
$mail = new PHPMailer();

$mail->From = "from@example.com";
$mail->FromName = "Full Name";
$mail->addReplyTo("reply@example.com", "Reply Address");
$mail->addAddress("recepient1@example.com", "Recepient Name");
$mail->addAddress("recepient2@example.com");
$mail->addCC("cc@example.com");
$mail->addBCC("bcc@example.com");
$mail->Subject = "Subject Text";
$mail->isHTML(true);
$mail->Body = "<html><body><p><b>This paragraph is bold.</b></p><p><i>This text is
italic.</i></p></body></html>";
$mail->AltBody = "This paragraph is not bold.\n\nThis text is not italic.";
if($mail->send()) {
    // (1)
    header('Location: http://example.com/path/to/thank-you.php', true, 303);
    exit;
}
else {
    echo "Error: " . $mail->ErrorInfo;
}

في الموضع (1) تكون الدالة أرجعت القيمة TRUE وسيُعاد التوجيه إلى صفحة thank-you، نستخدم النمط POST/REDIRECT/GET لمنع إعادة إرسال النموذج عندما يحدّث المستخدم الصفحة.

إرسال بريد إلكتروني مع مرفق باستخدام PHPMailer

<?php
$mail = new PHPMailer();

$mail->From = "from@example.com";
$mail->FromName = "Full Name";
$mail->addReplyTo("reply@example.com", "Reply Address");
$mail->Subject = "Subject Text";
$mail->Body = "This is a sample basic text email with an attachment using PHPMailer.";

// إضافة مرفق ثابت
$attachment = '/path/to/your/file.pdf';
$mail->AddAttachment($attachment , 'RenamedFile.pdf');

// ‫إضافة مرفق ثانٍ يُنشأ وقت التنفيذ مثل CSV ليُفتح باستخدام إكسل
$csvHeader = "header1,header2,header3";
$csvData = "row1col1,row1col2,row1col3\nrow2col1,row2col2,row2col3";

$mail->AddStringAttachment($csvHeader ."\n" . $csvData, 'your-csv-file.csv', 'base64', 'application/vnd.ms-excel');

if($mail->send()) {
    // (1)
    header('Location: http://example.com/path/to/thank-you.php', true, 303);
    exit;
}
else {
    echo "Error: " . $mail->ErrorInfo;
}

في الموضع (1) تكون الدالة أرجعت القيمة TRUE وسيُعاد التوجيه إلى صفحة thank-you، نستخدم النمط POST/REDIRECT/GET لمنع إعادة إرسال النموذج عندما يحدّث المستخدم الصفحة.

إرسال بريد إلكتروني يحتوي على نص بسيط باستخدام Sendgrid

بريد إلكتروني يحتوي على نص بسيط

<?php
$sendgrid = new SendGrid("YOUR_SENDGRID_API_KEY");
$email = new SendGrid\Email();

$email->addTo("recipient@example.com")
    ->setFrom("sender@example.com")
    ->setSubject("Subject Text")
    ->setText("This is a sample basic text email using ");

$sendgrid->send($email);

إضافة مستقبلين إضافيين، مستقبلين نسخة إضافية (CC)، مستقبلين نسخة إضافية محجوبين (BCC)

<?php
$sendgrid = new SendGrid("YOUR_SENDGRID_API_KEY");
$email = new SendGrid\Email();
$email->addTo("recipient@example.com")
    ->setFrom("sender@example.com")
    ->setSubject("Subject Text")
    ->setHtml("<html><body><p><b>This paragraph is bold.</b></p><p><i>This text is italic.</i></p></body></html>");

$personalization = new Personalization();
$email = new Email("Recepient Name", "recepient1@example.com");
$personalization->addTo($email);
$email = new Email("RecepientCC Name", "recepient2@example.com");
$personalization->addCc($email);
$email = new Email("RecepientBCC Name", "recepient3@example.com");
$personalization->addBcc($email);
$email->addPersonalization($personalization);

$sendgrid->send($email);

إرسال بريد إلكتروني مع مرفق باستخدام Sendgrid

إليك الشيفرة الكاملة:

<?php
$sendgrid = new SendGrid("YOUR_SENDGRID_API_KEY");
$email = new SendGrid\Email();

$email->addTo("recipient@example.com")
    ->setFrom("sender@example.com")
    ->setSubject("Subject Text")
    ->setText("This is a sample basic text email using ");

$attachment = '/path/to/your/file.pdf';
$content = file_get_contents($attachment);
$content = chunk_split(base64_encode($content));

$attachment = new Attachment();
$attachment->setContent($content);
$attachment->setType("application/pdf");
$attachment->setFilename("RenamedFile.pdf");
$attachment->setDisposition("attachment");
$email->addAttachment($attachment);

$sendgrid->send($email);

ترجمة -وبتصرف- للفصل [Sending Email] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: ملاحظات حول استعمال بروتوكول IMAP في PHP
• المقال السابق: استخدام MongoDB و Redis في PHP

كل شيء بين MongoDB و PHP

المتطلبات

• خادم MongoDB يعمل على منفذ والذي هو 27017 عادةً. (اكتب mongod في موجه الأوامر لتشغيل خادم mongod)
• لغة php مثبّتة إما باستخدام cgi أو fpm مع إضافة MongoDB (إضافة MongoDB لا توجد مع php بشكلٍ افتراضي).
• مكتبة المُنشئ (Composer) (‏mongodb/mongodb). نفّذ التعليمة php composer.phar require "mongodb/mongodb=^1.0.0"‎ في المجلد الجذر للمشروع لتثبيت مكتبة MongoDB).

إذا تأكدت من المتطلبات يمكنك بعدها الانتقال للخطوة التالية:

• التحقق من تثبيت php: نفّذ التعليمة php -v في موجه الأوامر إذا لم تكن متأكدًا من أنّها مثبّتة لديك وستُرجع مايشبه التالي:

PHP 7.0.6 (cli) (built: Apr 28 2016 14:12:14) ( ZTS ) Copyright (c) 1997-2016 The PHP Group Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies

• التحقق من تثبيت MongoDB: وذلك بتنفيذ التعليمة mongo --version والتي ستُرجع MongoDB shell version: 3.2.6.
• التحقق من تثبيت المُنشئ: وذلك بتنفيذ التعليمة php composer.phar --version التي ستُرجع Composer version 1.2-dev (3d09c17b489cd29a0c0b3b11e731987e7097797d) 2016-08-30 16:12:39.

الاتصال من php إلى MongoDB

<?php
// ‫يجب أن يشير هذا المسار إلى المحمِّل التلقائي للمُنشئ من المكان حيث يجب أن تُحمَّل مكتبة MongoDB 
 require 'vendor/autoload.php';

// استخدام اسم مستخدم وكلمة مرور مخصَّصَين
try { 
    $mongo = new MongoDB\Client('mongodb://username:password@localhost:27017');
    print_r($mongo->listDatabases()); 
} 
catch (Exception $e) { 
    echo $e->getMessage(); 
}

// استخدام إعدادات افتراضية
try { 
    $mongo = new MongoDB\Client('mongodb://localhost:27017');
    print_r($mongo->listDatabases()); 
} catch (Exception $e) { 
    echo $e->getMessage(); 
} 

ستتصل الشيفرة السابقة باستخدام مكتبة المُنشئ MongoDB (‏mongodb/mongodb) المضمّنة بالشكل vendor/autoload.php للاتصال بخادم MongoDB? الذي يعمل على المنفذ 27017. ستتصل إذا كان كل شيء صحيحًا وتعرض قائمة مصفوفة أما إذا حدث استثناء بالاتصال إلى خادم MongoDB? ستُطبع رسالة.

الإنشاء (الإضافة) في MongoDB

يستخدم MongoDB المجموعة (collection) بدلًا من الجداول كما هو الحال في SQL.

نستخدم في الشيفرة التالية الكائن ‎$mongo لاختيار قاعدة البيانات والمجموعة، إذا لم توجد قاعدة البيانات (demo في مثالنا) والمجموعة (beers في مثالنا) سينشئهما MongoDB تلقائيًا.

ونستخدم ‎$collection لإضافة ملف في MongoDB، يشبه الملف السطر في SQL، وكل ملف مُنشئ له معرِّف فريد.

<?php
$collection = $mongo->demo->beers;

$result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

echo "Inserted with Object ID '{$result->getInsertedId()}'"; 

استخدمنا في المثال الكائن ‎$mongo المستخدم سابقًا في شيفرة الاتصال من php إلى MongoDB، يستخدم MongoDB نوع تنسيق البيانات JSON لذا سنستخدم في php المصفوفة لإضافة بيانات إلى MongoDB، ستحوّل مكتبة mongo من المصفوفة إلى JSON وبالعكس، لكل ملف في MongoDB معرّف خاص به يمكننا الحصول عليه عند الإضافة باستخدام الشيفرة:

 $result->getInsertedId();

القراءة (البحث) في MongoDB

نستخدم التابع find()‎ للاستعلام عن السجلات، ويكون المعامل مصفوفة تتضمن زوج قيمة مفتاح نريد إيجاده، تُرجَع النتيجة على شكل مصفوفة ونستخدم foreach لفلترة المفاتيح المطلوبة.

$result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

foreach ($result as $entry) { 
    echo $entry['_id'], ': ', $entry['name'], "\n"; 
} 
?>

مثال آخر للبحث عن عدة مستخدمين اسمهم "Mike":

$filter = ['name' => 'Mike'];
$query = new \MongoDB\Driver\Query($filter);

$cursor = $manager->executeQuery('database_name.collection_name', $query); 
foreach ($cursor as $doc) { 
    var_dump($doc); 
}

ونستخدم التابع findOne()‎ للحصول على ملف واحد، مثال للبحث عن مستخدم واحد فقط له معرِّف محدد:

$options = ['limit' => 1]; 
$filter = ['_id' => new \MongoDB\BSON\ObjectID('578ff7c3648c940e008b457a')]; 
$query = new \MongoDB\Driver\Query($filter, $options); 

$cursor = $manager->executeQuery('database_name.collection_name', $query); 
$cursorArray = $cursor->toArray(); 
if(isset($cursorArray[0])) { 
    var_dump($cursorArray[0]); 
}

الحذف في MongoDB

تعيد الشيفرة التالية 1 في حال تم الحذف بنجاح وتعيد 0 في حال الفشل.

<?php
$result = $collection->drop( [ 'name' => 'Hinterland'] ); 
print_r($result->ok); 
?>

يمكنك الاطلاع في التوثيق الرسمي من MongoDB على العديد من التوابع التي يمكن تطبيقها على ‎$collection.

الاتصال مع MongoDB وإجراء العمليات

إنشاء اتصال MongoDB يمكنك استخدامه للاستعلام منه لاحقًا:

$manager = new \MongoDB\Driver\Manager('mongodb://localhost:27017');

ستتعلم في المثال التالي كيفية الاستعلام باستخدام كائن الاتصال، تُغلق هذه الإضافة الاتصال بشكلٍ تلقائي لذا ليس من الضروري إغلاقه يدويًا.

إضافة ملف

مثال لإضافة ملف:

$document = [ 
    'name' => 'John', 
    'active' => true, 
    'info' => ['genre' => 'male', 'age' => 30] 
]; 
$bulk = new \MongoDB\Driver\BulkWrite; 
$_id1 = $bulk->insert($document); 
$result = $manager->executeBulkWrite('database_name.collection_name', $bulk);

تحديث ملف

مثال لتحديث كل الملفات التي اسمها "John":

$filter = ['name' => 'John']; 
$document = ['name' => 'Mike']; 

$bulk = new \MongoDB\Driver\BulkWrite; 
$bulk->update( 
    $filter, 
    $document, 
    ['multi' => true] 
); 
$result = $manager->executeBulkWrite('database_name.collection_name', $bulk);

حذف ملف

مثال لحذف كل الملفات التي اسمها "Peter":

$bulk = new \MongoDB\Driver\BulkWrite; 

$filter = ['name' => 'Peter']; 
$bulk->delete($filter); 

$result = $manager->executeBulkWrite('database_name.collection_name', $bulk);

استخدام Redis مع PHP

الاتصال إلى كائن Redis

بفرض أنّ الخادم الافتراضي يعمل على المضيف المحلي مع المنفذ الافتراضي?، عندها يكون أمر الاتصال إلى خادم Redis هذا:

$redis = new Redis(); 
$redis->connect('127.0.0.1', 6379);

تثبيت PHP Redis على نظام التشغيل أبونتو

نثبّت أولًا خادم Redis:

sudo apt install redis-server 

ثم نثبّت وحدة PHP:

sudo apt install php-redis

ثم نعيد تشغيل خادم Apache:

sudo service apache2 restart

تنفيذ أوامر Redis في PHP

توفر وحدة Redis PHP الوصول إلى نفس الأوامر كعميل Redis CLI لذا يمكن استخدامها بشكلٍ مباشر.܏ الصياغة كالتالي:

// إنشاء مفتاحين جديدين
$redis->set('mykey-1', 123); 
$redis->set('mykey-2', 'abcd');

// الحصول على مفتاح واحد
// 123

‬// ‫الحصول على كل المفاتيح التي بدايتها 'my-key-‎‎'
var_dump($redis->keys('mykey-*'));
// '123', 'abcd'

الإضافة PDO في PHP

تسمح الإضافة PDO للمطورين بالاتصال بأنواع مختلفة كثيرة من قواعد البيانات وتنفيذ استعلامات مختلفة عليها بطريقة موحدة كائنية التوجه.

منع حقن SQL باستخدام استعلامات ذات وسائط

حقن SQL هو هجوم يسمح لمستخدم ضار بتعديل استعلام SQL بإضافة أوامر غير مرغوب بها إلى الاستعلام، مثلًا الاستعلام التالي معرَّض للخطر:

$sql = 'SELECT name, email, user_level FROM users WHERE userID = ' . $_GET['user'];
$conn->query($sql);

تسمح هذه الشيفرة لأي مستخدم بالتعديل في قاعدة البيانات بشكلٍ أساسي كما يرغب، مثلًا بفرض لدينا سلسلة الاستعلام التالية:

page.php?user=0;%20TRUNCATE%20TABLE%20users;

تجعل هذه السلسلة الاستعلام يكون بالشكل:

SELECT name, email, user_level FROM users WHERE userID = 0; TRUNCATE TABLE users;

يعدّ هذا المثال مبالغًا فيه (معظم هجمات حقن SQL لا تهدف إلى حذف البيانات ولا تدعم معظم دوال تنفيذ استعلام PHP الاستعلام المتعدد)، هذا مثال على إمكانية جعل هجوم حقن SQL ممكنًا من خلال التجميع غير المتقن للاستعلام، لسوء الحظ فإنَّ مثل هذه الهجمات شائع جدًا وفعال بشكلٍ كبير بسبب المبرمجين الذين يفشلون في اتخاذ الاحتياطات المناسبة لحماية بياناتهم.

الحل المناسب لمنع حدوث حقن SQL هو تعليمات التحضير (prepared statements)، فنستخدم عنصرًا بديلًا (placeholder) بدلًا من دمج بيانات المستخدم بشكلٍ مباشر مع الاستعلام، ثم تُرسَل البيانات بشكلٍ منفصل وبالتالي لا توجد فرصة لمحرك SQL أن يحتار بخصوص بيانات المستخدم. ولاحظ أنّ إضافة PHP MySQLi تدعم أيضًا تعليمات التحضير.

تدعم PDO نوعين من العناصر البديلة (لا يمكن استخدام العناصر البديلة لتسمية الأعمدة أو الجداول وإنما فقط للقيم):

1- العناصر البديلة المسماة، نقطتان (:) يتبعهما اسم واضح مثل (‎:user).

// استخدام العناصر البديلة المسماة
$sql = 'SELECT name, email, user_level FROM users WHERE userID = :user';
$prep = $conn->prepare($sql);

// مصفوفة ترابطية
$prep->execute(['user' => $_GET['user']]); 
$result = $prep->fetchAll();

2- العناصر البديلة الموضعية التقليدية في SQL تُمثَّل بالعلامة ?.

// استخدام العناصر البديلة الممثَّلة بعلامة الاستفهام
$sql = 'SELECT name, user_level FROM users WHERE userID = ? AND user_level = ?';
$prep = $conn->prepare($sql);

// مصفوفة مفهرسة
$prep->execute([$_GET['user'], $_GET['user_level']]);
$result = $prep->fetchAll();

يجب أن تعلم أنّه إذا احتجت إلى تغيير اسم عمود أو جدول بشكلٍ ديناميكي فإنّ هذه ممارسة سيئة وعلى مسؤوليتك الأمنية الخاصة، مع أنّه يمكنك القيام بذلك عن طريق دمج السلاسل النصية. إحدى الطرق لتحسين أمان مثل هذه الاستعلامات هي تعيين جدول فيه القيم المسموح بها ومقارنة القيمة التي تريدها للدمج مع هذا الجدول.

يجب أن تعلم أنّه من المهم ضبط ترميز محارف الاتصال ليكون DSN (‏Data Source Name) فقط، وإلا قد يكون تطبيقك معرّضًا لثغرة ضعيفة. إنّ ضبط ترميز المحارف ليكون DSN غير متاح في الإصدارات PDO السابقة للإصدار 5.3.6 لذا فالخيار الوحيد هو ضبط سمة الاتصال PDO::ATTR_EMULATE_PREPARES لتكون false مباشرةً بعد إنشائه.

$conn->setAttribute(PDO::ATTR_EMULATE_PREPARES, false);

ستؤدي هذه الشيفرة إلى استخدام PDO لتعليمات التحضير الأساسية الموجودة في DBMS (‏Database Management Systems) بدلًا من محاكاتها فقط، وانتبه إلى أنّ PDO ستتراجع ببطء لمحاكاة التعليمات التي لا تستطيع MySQL تحضيرها محليًّا، هذه العبارات موجودة في التوثيق.

اتصال PDO الأساسي والاسترجاع

بدءًا من الإصدار PHP 5.0 أصبحت PDO متاحة كطبقة وصول إلى قاعدة البيانات، وهي لا تعرف قاعدة البيانات، ستعمل الشيفرة في مثال الاتصال التالي لأي من قواعد البيانات المدعومة ببساطة عن طريق تغيير الترميز DSN.

// (1)
$dsn = "mysql:host=localhost;dbname=testdb;charset=utf8";

// (2)
$username = "user";
$password = "pass";
$db = new PDO($dsn, $username, $password);

// ‫ضبط PDO لرمي استثناء إذا أُدخِل استعلام غير صحيح
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

// تحضير تعليمة التنفيذ مع عنصر بديل مفرد
$query = "SELECT * FROM users WHERE class = ?";
$statement = $db->prepare($query);

// إنشاء بعض المعاملات لملء العناصر البديلة وتنفيذ التعليمة
$parameters = [ "221B" ];
$statement->execute($parameters);

// التكرار على كل سجل كمصفوفة ترابطية
while ($row = $statement->fetch(PDO::FETCH_ASSOC)) {
    do_stuff($row);
}

ننشئ في الموضع (1) مقبضًا لقاعدة البيانات ونستخدم MySQL (اتصال باستخدام مقبس محلي) يوضّح الموضع (2) أنّه يمكنك استخدام MySQL (اتصال عبر الشبكة، يمكنك تحديد المنفذ أيضًا إذا أردت) باستخدام الشيفرة:

$dsn = "mysql:host=127.0.0.1;port=3306;dbname=testdb;charset=utf8";

أو استخدام Postgres:

$dsn = "pgsql:host=localhost;port=5432;dbname=testdb;";

أو حتى SQLite:

$dsn = "sqlite:/path/to/database"

تنشئ الدالة prepare كائنًا من الصنف PDOStatement من سلسلة الاستعلام، تجري عمليات تنفيذ الاستعلام واسترجاع النتائج على هذا الكائن المُرجَع. في حال الفشل إما تعيد الدالة false أو ترمي استثناءً (بالاعتماد على كيفية ضبط إعدادات اتصال PDO).

عمليات قاعدة البيانات مع PDO

تضمن عمليات (transactions) قاعدة البيانات أنَّ مجموعة التغييرات على قاعدة البيانات ستصبح دائمة فقط إذا نجحت كل التعليمات، يمكن التقاط أي فشل في الاستعلام أو الشيفرة خلال عملية ما ثم يكون لديك خيار التراجع (roll back) عن التغييرات التي حاولت القيام بها. توفر PDO توابع بسيطة لعمليات البدء وحفظ التغييرات (committing) والتراجع.

$pdo = new PDO(
    $dsn,
    $username,
    $password,
    array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION)
);

try {
    $statement = $pdo->prepare("UPDATE user SET name = :name");
    $pdo->beginTransaction();
    $statement->execute(["name"=>'Bob']);
    $statement->execute(["name"=>'Joe']);
    $pdo->commit();
}

catch (\Exception $e) {
    if ($pdo->inTransaction()) {
        $pdo->rollback();
        // إذا وصلنا إلى هنا فإنَّ التحديثين ليسا في قاعدة البيانات
    }
    throw $e;
}

تكون أي تغييرات تُجرى على البيانات خلال العملية مرئية للاتصال النشط، ستُرجع تعليمات SELECT التغييرات المُعدَّلة حتى لو لم تُحفظ في قاعدة البيانات بعد.

مثال عملي لاستخدام العمليات مع PDO

نعرض لك في الفقرة التالية مثال عملي من العالم الحقيقي حيث يضمن استخدام العمليات اتساق قاعدة البيانات.

تخيل بأنّك تبني عربة تسوق لموقع تجارة الكترونية وقررت أن تحتفظ بطلبات العملاء في جدولين من قاعدة البيانات، اسم الجدول الأول orders يعبر عن الطلبات وحقوله هي order_id، ‏name، ‏address، ‏telephone و‏created_at، واسم الجدول الثاني orders_products يحوي منتجات الطلبات وحقوله هي order_id،‏product_id وquantity، أي يحتوي الجدول الأول على بيانات وصفية للطلب والجدول الثاني على المنتجات الفعلية التي طلبها العملاء.

إضافة طلب جديد إلى قاعدة البيانات

تحتاج لإضافة طلب جديد إلى قاعدة البيانات إلى أمرين، الأول هو إنشاء سجل جديد (INSERT) في الجدول orders يحتوي على البيانات الوصفية للطلب (الاسم والعنوان وغير ذلك)، والثاني هو إنشاء سجل جديد في الجدول orders_products لكل منتج من المنتجات الموجودة في قائمة الطلب. يمكنك القيام بذلك باستخدام الشيفرة التالية:

// إضافة البيانات الوصفية للطلب في قاعدة البيانات
$preparedStatement = $db->prepare(
    'INSERT INTO `orders` (`name`, `address`, `telephone`, `created_at`)
    VALUES (:name, :address, :telephone, :created_at)'
);

$preparedStatement->execute([
    'name' => $name,
    'address' => $address,
    'telephone' => $telephone,
    'created_at' => time(),
]);

// ‫الحصول على `order_id` المولَّد
$orderId = $db->lastInsertId();

// بناء استعلام لإضافة منتجات الطلب
$insertProductsQuery = 'INSERT INTO `orders_products` (`order_id`, `product_id`, `quantity`) VALUES';

$count = 0;
foreach ( $products as $productId => $quantity ) {
    $insertProductsQuery .= ' (:order_id' . $count . ', :product_id' . $count . ', :quantity' . $count . ')';
    $insertProductsParams['order_id' . $count] = $orderId;
    $insertProductsParams['product_id' . $count] = $productId;
    $insertProductsParams['quantity' . $count] = $quantity;

    ++$count;
}

// إضافة المنتجات المُضمَّنة في الطلب إلى قاعدة البيانات
$preparedStatement = $db->prepare($insertProductsQuery);
$preparedStatement->execute($insertProductsParams);

ستعمل هذه الشيفرة بشكلٍ رائع على إضافة طلب جديد إلى قاعدة البيانات حتى يحدث شيء ما غير متوقع ولسببٍ ما يفشل استعلام INSERT الثاني وعندها سيكون لديك طلب جديد في الجدول orders بدون وجود منتجات مرتبطة فيه من الجدول orders_products. لحسن الحظ يمكن إصلاح هذا ببساطة بجعل الاستعلامين في عملية قاعدة بيانات واحدة.

إضافة طلب جديد إلى قاعدة البيانات مع عملية

كل ماعليك فعله لبدء عملية باستخدام PDO هو استدعاء التابع beginTransaction قبل تنفيذ أي استعلامات على قاعدة البيانات، ثم تجري التغييرات التي تريدها بتنفيذ استعلامات INSERT و/أو UPDATE وفي النهاية تستدعي التابع commit للكائن لجعل التغييرات دائمة، قبل استدعاء التابع commit فإنّ كل التغييرات التي تجريها على بياناتك غير دائمة ويمكن التراجع عنها بسهولة باستدعاء التابع rollback للكائن PDO.

نوضح في المثال التالي استخدام العمليات لإضافة طلب جديد في قاعدة البيانات مع ضمان اتساق البيانات في نفس الوقت، ستُرجع جميع التغييرات إذا فشل أحد الاستعلامين، نستخدم في هذا المثال MySQL لكن يمكن تطبيقه على أي قاعدة بيانات تدعم العمليات.

$db = new PDO('mysql:host=' . $host . ';dbname=' . $dbname . ';charset=utf8', $username,$password);

// ‫تأكد من أنّ PDO سترمي استثناءً في حالة الخطأ لجعل عملية معالجة الخطأ أسهل
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

try {
    // بدءًا من هذه النقطة وحتى تُحفظ العملية يمكن التراجع عن كل تغيير في قاعدة البيانات
    $db->beginTransaction();

    // إضافة البيانات الوصفية للطلب في قاعدة البيانات
    $preparedStatement = $db->prepare(
        'INSERT INTO `orders` (`order_id`, `name`, `address`, `created_at`)
        VALUES (:name, :address, :telephone, :created_at)'
    );

    $preparedStatement->execute([
        'name' => $name,
        'address' => $address,
        'telephone' => $telephone,
        'created_at' => time(),
    ]);

    // ‫الحصول على `order_id` المولَّد
    $orderId = $db->lastInsertId();

    // بناء الاستعلام لإضافة منتجات الطلب
    $insertProductsQuery = 'INSERT INTO `orders_products` (`order_id`,     `product_id`, `quantity`) VALUES';

    $count = 0;
    foreach ( $products as $productId => $quantity ) {
        $insertProductsQuery .= ' (:order_id' . $count . ', :product_id' . $count . ',     :quantity' . $count . ')';

        $insertProductsParams['order_id' . $count] = $orderId;
        $insertProductsParams['product_id' . $count] = $productId;
        $insertProductsParams['quantity' . $count] = $quantity;
        ++$count;
    }

    // إضافة منتجات الطلب إلى قاعدة البيانات
    $preparedStatement = $db->prepare($insertProductsQuery);
    $preparedStatement->execute($insertProductsParams);

    // جعل تغييرات قاعدة البيانات دائمة
    $db->commit();
}
catch ( PDOException $e ) {
    // فشل إضافة الطلب في قاعدة البيانات لذا نتراجع عن التغييرات
    $db->rollback();
    throw $e;
}